Blog

Circle API の使い方：USDC決済、ウォレット、払い出し

Ashley Innocent

Ashley Innocent

23 4月 2026

Circle API の使い方：USDC決済、ウォレット、払い出し

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

Circleは、時価総額で2番目に大きいステーブルコインであるUSDCを発行しており、カストディ、コンプライアンス、またはバンキングインフラをゼロから構築することなく、オンチェーンでドルを移動できる一連のAPIを公開しています。マーケットプレイスの支払いを数分で決済したい、ユーザーがカードで入金しUSDCとして出金できるようにしたい、または1回の呼び出しで8つのブロックチェーン間でステーブルコインを移動させたいと思ったことがあるなら、Circle APIがその最短経路です。公式ドキュメントはdevelopers.circle.comで公開されており、鍵を触る前にcircle.com/en/usdcにあるUSDC入門を読んでおく価値があります。

このガイドでは、アカウント作成、サンドボックスとプロダクション、Bearerトークン認証、支払いとペイアウトのエンドポイント、Circle Wallets（Web3サービス）、Cross-Chain Transfer Protocol（CCTP）、Developer-Controlled Walletsのためのエンティティシークレットの暗号文、Webhook、冪等性（べきとうせい）、およびKYBコンプライアンスといった、開発者向けの機能全体を解説します。ターミナルに貼り付けられる`curl`およびNodeのスニペットも掲載しています。関連資料: 最高のフィアットオンランプ・オフランプAPIに関する当社のガイドでは、Circleを競合他社と比較しています。

💡
プロトタイプ作成中は、RESTとWeb3の両方に精通したAPIクライアントも必要になるでしょう。Apidogは、CircleのBearer認証、環境切り替え、Webhookリプレイを1つのワークスペースで処理するため、コレクションを書き直すことなくサンドボックスとプロダクションを並行してテストできます。

ボタン

TL;DR（要約）

Circle APIとは？

Circleは、USDCを発行し、それを米ドルにペッグする基盤を運用する、規制された決済企業です。Circle APIは、組み合わせ可能な4つのプロダクトラインを公開しています。

Circleを汎用的なWeb3インフラと比較している場合は、各ツールがどこに適合するかを確認するために、最高のクリプトウォレットAPIの内訳とAlchemy APIの使い方ガイドを読んでください。

認証とセットアップ

console.circle.comでアカウントを作成してください。コンソールにはサンドボックスとプロダクションの2つの環境があります。サンドボックスは無料でセルフサービスですが、プロダクションにはKnow Your Business（KYB）の承認が必要で、これには数営業日かかり、法人登記書類、実質的支配者情報、資金調達アカウントが必要です。

開発者 → APIキーからAPIキーを生成してください。キーの形式は、サンドボックスではTEST_API_KEY:<id>:<secret>、プロダクションではLIVE_API_KEY:<id>:<secret>です。Bearerトークンとして渡します。

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

ベースURL:

W3SのDeveloper-Controlled Walletsには、エンティティシークレットも必要です。これは、一度生成してダッシュボードから登録する32バイトの16進数文字列です。すべての書き込み呼び出しには、CircleのRSA公開鍵で暗号化された新しいentitySecretCiphertextを含める必要があります。Node SDKはこれを自動的に再生成しますが、自分で実装する場合は、Circleが再利用された値を拒否するため、リクエストごとに暗号文をローテーションしてください。

Node SDKをインストールします:

npm install @circle-fin/developer-controlled-wallets

コアエンドポイント

ウォレットセットとウォレットを作成

W3Sのウォレットは、ウォレットセット（1つのHDシードを共有するグループ）内に存在します。最初にセットを作成し、その中にウォレットを生成します。

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

各ウォレットはid、address、およびそれが存在するブロックチェーンを返します。続行するには、CircleのファセットからテストネットのUSDCで資金を供給してください。

開発者管理ウォレットからUSDCを送金

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

応答は、GET /v1/w3s/transactions/{id}を通じてポーリングするか、Webhookを通じてリッスンするトランザクションidを返します。

カード決済を受け付け、USDCとして決済

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

カードデータは、Circleの公開鍵（/v1/encryption/publicから取得）でPGP暗号化されている必要があります。応答は、pending → confirmed → paidと遷移する支払いidを返します。

電信送金またはACHで支払い（ペイアウト）を送信

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

CCTPでUSDCをクロスチェーン移動

CCTPはスマートコントラクトプロトコルであり、RESTエンドポイントではないため、オンチェーンでのバーンとCircleのアテステーションサービスを組み合わせます。

  1. ソースチェーン上のTokenMessengerコントラクトでdepositForBurnを呼び出します。
  2. status: "complete"になり、attestationの16進数blobを受け取るまで、https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash}をポーリングします。
  3. メッセージバイトとアテステーションを使って、デスティネーションチェーン上のMessageTransmitterコントラクトでreceiveMessageを呼び出します。

検証可能なバーンに対して、デスティネーションチェーンでネイティブUSDCがゼロからミントされます。ラップされたトークンはなく、ブリッジの流動性リスクもありません。

Webhookと冪等性

Circleは、payments、payouts、transfers、chargebacksといったイベントを、/v1/notifications/subscriptions経由で購読したHTTPSエンドポイントにPOSTします。すべてのWebhookはECDSAキーで署名されています。ペイロードを信頼する前に、/v1/notifications/publicKey/getから公開鍵を取得し、X-Circle-Signatureヘッダーを検証してください。

すべての変更を伴うエンドポイントには、Idempotency-Keyヘッダー（UUID v4が標準）が必要です。同じキーでリクエストを再試行すると、重複した支払いを作成する代わりに元の応答が返されます。これは重要です。カードや電信送金は二重送信を許しません。

一般的なエラーとレート制限

カードインフラに関するより広い視点については、最高のカード発行APIに関する当社のまとめで、Circleのペイアウトと相性の良い発行会社をカバーしています。

Circle APIの料金

サンドボックスは無料です。プロダクションでは、Circle Mintは、条件を満たす機関投資家顧客に対してUSDCの発行または償還に料金を請求しません。Circle Paymentsは、カード取引ごとにパーセンテージと固定手数料を徴収します（通常は2.9% + 30セントですが、規模に応じて交渉されます）。米国への電信送金によるペイアウトは、取引あたり数ドルかかります。W3Sウォレットはウォレットごと、取引ごとに料金が設定されます。プロダクションの見積もりについては営業にお問い合わせください。CCTP自体は無料ですが、ソースチェーンとデスティネーションチェーンのガス代はユーザーが負担します。

ApidogでCircle APIをテストする

CircleのサービスはREST、署名付きWebhook、オンチェーンコントラクトに及び、単一のPostmanコレクションでは全体のフローを網羅することはほとんどできません。ApidogはCircleのOpenAPI仕様を直接インポートし、サンドボックスとプロダクションのBearerトークンを別々の環境として保存し、カード支払い、ペイアウト、Webhook検証を一連の流れとして実行するテストスクリプトを作成できます。

Apidogをダウンロードし、Circleの開発者ポータルからCircleの仕様を読み込んでください。検証ハンドラを構築中にモックサーバーを使用してWebhookの配信をシミュレートし、準備ができたら実際のEndpointに切り替えてください。チームの場合、共有ワークスペースはエンティティシークレットをチャットから遠ざけ、コレクションをバックエンドコードと一緒にバージョン管理します。

FAQ（よくある質問）

Circle APIをテストするのにKYBが必要ですか？いいえ、必要ありません。サンドボックスアカウントはEメールアドレスを持つ誰でも利用できます。KYBはプロダクション環境で実際のドルを移動させる場合にのみ必要です。サンドボックスには、サポートされているすべてのチェーン用のUSDCファセットが付属しています。

Circle MintとCircle Walletsの違いは何ですか？Circle Mintは、機関投資家向けのオンランプです。米ドルを入金し、USDCを出金します（逆も同様）。Circle Wallets / W3Sは、エンドユーザー向けのカストディおよびトランザクションインフラです。ほとんどの消費者向けアプリはWalletsを上に使用し、財務アプリはMintを直接使用します。MoonPay APIの使い方ガイドでは、Mintレベルの発行が必要ない場合の、リテール限定の代替案を紹介しています。

CCTPはどのようにブリッジリスクを回避しますか？ネイティブUSDCはソースチェーンでバーンされ、Circleからの署名付きアテステーションに基づいてデスティネーションチェーンで新しくミントされます。ブリッジの悪用によって枯渇する可能性のあるロックされた流動性プールはありません。Circleのアテステーションサービスを信頼する必要はありますが、サードパーティのブリッジバリデータセットを信頼する必要はありません。

鍵を保持せずにCircle Walletsを使用できますか？はい。W3SのUser-Controlled WalletsはMPCおよびPINベースの認証を使用するため、エンドユーザーはCircleのSDKを通じてトランザクションを承認し、開発者が秘密鍵に触れることはありません。Developer-Controlled Walletsは、エンティティシークレットを通じてバックエンドに署名権限を置きます。

CircleはSolanaや非EVMチェーンをサポートしていますか？はい。W3SはSolana、Aptos、NEAR、およびいくつかのEVM L2をカバーしています。CCTP v2は2024年にSolanaのサポートを拡張したため、ネイティブUSDCはSolanaとEVMエコシステム間で自由に移動できるようになりました。

エンティティシークレットを安全にローテーションするにはどうすればよいですか？Circleはダッシュボード経由でのエンティティシークレットのローテーションをサポートしています。新しいシークレットを生成して登録し、短い切り替え期間中は古い暗号文と新しい暗号文の両方を並行して実行してください。SDKは環境変数内のいずれかのシークレットを読み取るため、ローリングデプロイでクリーンに処理できます。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード