DEV Community

Cover image for MoonPay APIの使い方：法定通貨オンランプとオフランプの連携
Akira
Akira

Posted on • Originally published at apidog.com

MoonPay APIの使い方：法定通貨オンランプとオフランプの連携

法定通貨から仮想通貨へのオンランプは、従来は煩雑なコンプライアンス書類、銀行との連携、KYCベンダーの統合が必要でした。MoonPay APIを使えば、署名付きURLを生成してウィジェットをアプリに組み込むだけで、カード決済・銀行振込・本人確認・ウォレットへの送金までを一気通貫で実現できます。

Apidogを今すぐ試してみよう

本ガイドでは、MoonPay APIをエンドツーエンドで実装する方法を解説します。パートナーアカウントのセットアップから、ウィジェットとAPIの選択、署名付きURL構築、Webhook検証、売却フロー、NFTチェックアウト、コンプライアンス制限までを実際のリクエスト例を交えて説明します。すべてのリクエストはサンドボックスで検証済みで、MoonPay公式開発者ポータルに準拠しています。Apidogを使えば同じAPIコールを即座にテストできます。

まだ比較検討段階の場合は、最適な法定通貨オンランプ/オフランプAPIまとめや、Circle APIの使い方も参考にしてください。

TL;DR

  • MoonPayは160カ国以上で利用される規制準拠のオンランプ/オフランプAPI。
  • 統合方法は2パターン：Ramps SDK/ウィジェット（最速）またはREST API（フルコントロール）。
  • すべてのウィジェットURLはHMAC-SHA256署名が必須。未署名URLは本番で拒否。
  • KYCや決済処理はMoonPay側で完結し、WebhookをHMACで検証して受信。
  • 手数料はカード3.5%～4.5%、銀行は1%～1.9%。ネットワーク手数料も明示。
  • 売却フローも購入と同様。署名付きURL→ユーザーが仮想通貨送付→MoonPayが銀行に送金。

MoonPayとは？

MoonPayは、カード・銀行振込・Apple Pay・Google Pay・SEPAなど多様な決済手段で仮想通貨の売買を可能にする決済プロバイダーです。米国、EU、イギリス、カナダ、オーストラリアで認可を取得済み。ウォレットやNFTマーケットプレイス、取引所で採用されており、Ethereum、Solana、Bitcoin、Polygonなど40以上のネットワーク・110以上の仮想通貨に対応しています。

認証と設定

  1. moonpay.com/businessでパートナーアカウントを作成。
  2. 承認後、サンドボックス・本番用のAPIキー（pk_test/sk_test...）が発行されます。秘密キーは厳重管理し、URL署名・Webhook検証に使用。
  3. 環境変数を設定： 
    export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"
  4. サンドボックスは本番と同じエンドポイントでテスト可能。最終的に本番キーへ切り替えて運用。

コアエンドポイント

MoonPayの主要エンドポイントは「通貨一覧」「見積もり」「トランザクション」「Webhook」など。RESTリファレンスで全エンドポイントを確認できます。

対応通貨を取得

ユーザーの国や地域でフィルタした上で通貨リストを取得：

curl -X GET "https://api.moonpay.com/v3/currencies" \
  -H "Authorization: Api-Key $MOONPAY_API_KEY"

レスポンスには、code, name, type, minBuyAmount, maxBuyAmount, ネットワークごとのメタデータが含まれます。

リアルタイム見積もり取得

ユーザーが購入前に正確な数量・手数料を確認できるようにする：

curl -X GET "https://api.moonpay.com/v3/currencies/eth/buy_quote?apiKey=$MOONPAY_API_KEY&baseCurrencyAmount=100&baseCurrencyCode=usd" \
  -H "Content-Type: application/json"

quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmountが返ります。見積もりは60秒キャッシュ可能。

署名付き購入ウィジェットURLを生成（Node.js）

Node.jsで署名付きURLを動的生成し、iframeやリダイレクトでウィジェットを組み込みます：

import crypto from "node:crypto";

function buildMoonPayBuyUrl({ walletAddress, currencyCode, baseAmount, email }) {
  const params = new URLSearchParams({
    apiKey: process.env.MOONPAY_API_KEY,
    currencyCode,
    walletAddress,
    baseCurrencyCode: "usd",
    baseCurrencyAmount: String(baseAmount),
    email,
    redirectURL: "https://yourapp.com/moonpay/complete",
  });

  const originalUrl = `https://buy.moonpay.com?${params.toString()}`;

  const signature = crypto
    .createHmac("sha256", process.env.MOONPAY_SECRET_KEY)
    .update(new URL(originalUrl).search)
    .digest("base64");

  return `${originalUrl}&signature=${encodeURIComponent(signature)}`;
}

このURLをユーザーに渡せばOK。パラメータ改ざん対策として署名必須です。公式クイックスタートも参照。

Webhook署名の検証

Webhookで着信したイベントは必ずHMAC-SHA256で署名検証を行うこと：

import crypto from "node:crypto";

export function verifyMoonPayWebhook(rawBody, header, secret) {
  const [tPart, sPart] = header.split(",");
  const timestamp = tPart.split("=")[1];
  const signature = sPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

5分以上前のリクエストはリプレイ攻撃の可能性があるため拒否してください。Webhookリファレンスも必読。

売却（オフランプ）フロー

売却時はsell.moonpay.comの署名付きURLを使い、仮想通貨を送金したユーザーに法定通貨を返金：

const sellParams = new URLSearchParams({
  apiKey: process.env.MOONPAY_API_KEY,
  baseCurrencyCode: "eth",
  baseCurrencyAmount: "0.5",
  quoteCurrencyCode: "usd",
  refundWalletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbc",
});

const sellUrl = `https://sell.moonpay.com?${sellParams.toString()}`;
// 購入URL同様に署名を付与

refundWalletAddressは誤送信時やKYC失敗時の返金先として必須。

NFTチェックアウト

MoonPayにNFTリストを登録し、署名付きURL（contractAddress・tokenId・listingId含む）を生成するだけで、法定通貨→NFT購入→オンチェーン転送までを自動化できます。高額NFTの一次販売でも離脱率を大幅に低減可能。

よくあるエラーとレート制限

  • 400 invalid_signature：署名対象のクエリ文字列が送信時と一致しない場合。URLエンコードの違いに注意。
  • 403 geo_restricted：対象地域外。isAllowedフィールドで事前チェックを。
  • 422 transaction_limit_exceeded：KYC済でもユーザーごとに日次/週次/月次上限あり。
  • 429 rate_limited：APIキーごとに1分100リクエスト程度。通貨リスト・見積もりはキャッシュ推奨。

取引状態はユーザーUIではなくWebhookのtransaction_updated（status: completed）で判定してください。

マルチウォレットやKYC統合については、MetaMask APIの使い方・仮想通貨ウォレットAPIまとめ・KYC APIまとめも参考にしてください。

MoonPayの料金

  • カード購入: 3.5%～4.5%（最低$3.99）
  • 銀行振込（ACH・SEPA等）: 1%～1.9%
  • ネットワーク手数料: 実費をユーザーに転嫁
  • 売却フロー: 送金手段によって同様のフィー体系

レベニューシェアや大規模統合向けのカスタム料金は個別交渉となります。

ApidogでMoonPayをテストする

MoonPayの統合で最もエラーが起きやすい署名付きURL・WebhookのHMAC検証も、ApidogならGUI上で高速デバッグ可能です。OpenAPI仕様をインポートし、環境変数でsandbox/production切り替え、Nodeスニペットをプレリクエストフック化することで、トランザクション全体のフローを再現できます。

おすすめワークフロー：sandbox/production環境を作り、署名生成をスクリプト化、サンプル取引IDを変数化、Webhookの生データをApidogのモックサーバーで再送信して検証までを一元管理。Apidogをダウンロードし、署名フック・モックサーバー・環境切り替えを活用しましょう。

よくある質問

MoonPay以外に独自のKYCベンダーは必要？
不要です。MoonPayのサーバー側でKYC処理が完了します。他用途ならKYC API比較も参照。

MoonPayのブランド入りウィジェットを非表示で利用できる？
APIやヘッドレスSDK経由で可能ですが、追加のコンプライアンス審査が必要。まずはウィジェット導入→取引量増加後に移行が推奨。

MoonPayの対応国は？
購入は160カ国超、売却は約50カ国。通貨・決済手段は地域ごとに異なります。通貨APIで動的チェック推奨。

決済にかかる時間は？
カードなら通常5分以内、銀行振込は1～3営業日、売却はオンチェーン確認後1～3日で銀行に着金。

Webhook配信エラー時は？
最大24時間指数バックオフで再試行。重複イベントはidで排除必須。

サンドボックスは本番と同等？
概ね同等ですが、地理制限やKYCが緩和/バイパスされています。本番用のスモークテストは必須です。

Top comments (0)