Akira

Posted on Apr 23 • Originally published at apidog.com

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

Circleは、時価総額で2番目に大きいステーブルコインであるUSDCを発行しており、カストディ、コンプライアンス、バンキングインフラをゼロから構築することなくオンチェーンでドルを移動できるAPI群を提供しています。数分でマーケットプレイスの支払いを決済したい、カードから入金しUSDCで出金したい、複数チェーン間でステーブルコインを移動したい場合、Circle APIが最短ルートです。公式ドキュメントはdevelopers.circle.com、USDC入門はcircle.com/en/usdcにあります。

今すぐApidogを試そう

このガイドでは、アカウント作成、サンドボックス/プロダクション環境、Bearerトークン認証、支払い・ペイアウトエンドポイント、Circle Wallets（Web3サービス）、Cross-Chain Transfer Protocol（CCTP）、Developer-Controlled Wallets向けエンティティシークレット暗号文、Webhook、冪等性、KYBコンプライアンスまで、開発者が実装するための具体的な手順を説明します。`curl`やNode.jsのスニペットも掲載。関連資料: 最高のフィアットオンランプ・オフランプAPIガイドでは、Circleと他サービスの比較もしています。

💡プロトタイプ作成時はRESTとWeb3両対応のAPIクライアントが必須です。ApidogならCircleのBearer認証・環境切り替え・Webhookリプレイを1ワークスペースで処理でき、コレクションの書き換えなしにサンドボックスとプロダクションを並行テスト可能です。

TL;DR（要約）

Circle APIは、Circle Payments（カード・ACH・電信送金）、Circle Mint（USDC発行）、Circle Wallets/W3S（プログラマブルウォレット）、CCTP（クロスチェーンUSDC転送）などを提供。
Bearerトークン認証。サンドボックスはTEST_API_KEY:～、プロダクションはLIVE_API_KEY:～形式。
Developer-Controlled Walletsでは、書き込み時にRSA暗号化したエンティティシークレットの暗号文が必須（リクエストごとに再生成）。
CCTPはEthereum/Arbitrum/Base/Optimism/Polygon PoS/Avalanche/Solana等でバーン＆ミントによりUSDCをクロスチェーン移動。
プロダクションにはKYB承認が必要、サンドボックスは誰でも利用可。
すべての変更系リクエストは冪等性キーを使い、Webhook署名は/notifications/publicKey/getから取得した公開鍵で検証。

Circle APIとは？

CircleはUSDCの発行、米ドルペグ運用を担う規制決済企業です。Circle APIは以下4つのプロダクトラインを提供します。

Circle Payments API: カード/ACH/SEPA/電信送金を受けてUSDCとして決済。
Circle Payouts API: USDC残高から登録済み銀行口座へ電信送金またはACH送信。
Circle Wallets (W3S): 複数チェーンでカストディアル/開発者管理ウォレットを作成、署名、ガス処理。
CCTP: ソースチェーンでUSDCバーン、デスティネーションチェーンでUSDCミント。ラップトークン無、ネイティブ資産。

他のWeb3インフラとの比較はクリプトウォレットAPIやAlchemy APIの使い方も参照。

認証とセットアップ

console.circle.comでアカウント作成。
サンドボックス（無料セルフサービス）/プロダクション（KYB承認必要）2環境あり。プロダクションは法人登記書・実質支配者・資金調達口座の情報提出が必要。
「開発者 → 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

サンドボックス: https://api-sandbox.circle.com
プロダクション: https://api.circle.com

Developer-Controlled Walletsのエンティティシークレット

ダッシュボードで32バイト16進数文字列を生成・登録。
すべての書き込みAPI呼び出し時にRSA公開鍵で暗号化したentitySecretCiphertextを含める（リクエストごとにローテーション必須）。
Node SDK利用時は自動ローテーション。手動実装時は再利用NG。

Node SDKインストール:

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

コアエンドポイント

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

W3Sウォレットは「ウォレットセット」（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" } },
});

応答にはidが含まれ、GET /v1/w3s/transactions/{id}でポーリングまたはWebhookで監視します。

カード決済を受け付け、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暗号化必須。応答で支払いidを取得し、pending → confirmed → paidに遷移。

電信送金または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 APIではなくスマートコントラクトプロトコル。オンチェーンでバーン＆Circleのアテステーションサービスを利用します。

ソースチェーンのTokenMessengerコントラクトでdepositForBurn呼び出し。
https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash}でstatus: "complete"・attestationの16進数blob取得までポーリング。
メッセージバイトとアテステーションで、デスティネーションチェーンのMessageTransmitterコントラクトでreceiveMessage呼び出し。

これによりラップドトークンなし、流動性リスクなしでネイティブUSDCがミントされます。

Webhookと冪等性

Circleはpayments・payouts・transfers・chargebacks等イベントを/v1/notifications/subscriptionsで購読したHTTPSエンドポイントにPOST。
すべてのWebhookはECDSA署名。/v1/notifications/publicKey/getで公開鍵取得、X-Circle-Signatureヘッダー検証必須。
変更系APIにはIdempotency-Key（UUID v4推奨）が必要。同一キーで再試行時は重複作成されず元応答返却。カードや送金の二重送信防止に必須。

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

401 Unauthorized: Bearerトークン欠如/形式不正/環境違い。
400 invalid_entity_secret_ciphertext: 暗号文再利用または古い公開鍵利用。再生成で解決。
429 Too Many Requests: サンドボックスはエンドポイントごと毎秒10リクエスト制限。プロダクションはスケール型。指数バックオフ推奨。
insufficient_funds: 残高不足またはカードがAVS/CVVエラー。

カードインフラ全体像や発行会社比較はカード発行APIまとめもチェック。

Circle APIの料金

サンドボックスは無料。
プロダクション:
- Circle Mint: 条件を満たす機関投資家はUSDC発行/償還無料。
- Circle Payments: 取引ごとに2.9% + 30セント（規模で交渉可）。
- ペイアウト（電信送金）は数ドル/件。
- W3Sウォレットはウォレット数・取引数で課金。
- CCTP自体は無料（チェーンのガス代は利用者負担）。
見積もりは営業に問い合わせ。

ApidogでCircle APIをテストする

CircleのAPIはREST、署名Webhook、オンチェーンコントラクトまで多岐にわたるため、Postmanコレクションだけでは全フローを網羅しきれません。ApidogならCircleのOpenAPI仕様を直接インポートし、サンドボックス/プロダクションのBearerトークンを環境ごとに管理、カード決済・ペイアウト・Webhook検証を一連のテストスクリプトとして実行可能です。

Apidogをダウンロードし、Circle開発者ポータルから仕様を読み込みましょう。Webhookハンドラ開発時はモックサーバーで配信をシミュレート、本番準備ができたら実エンドポイントに切り替え。チームで使う場合、共有ワークスペースでエンティティシークレットを安全に管理し、コレクションはバックエンドコードと一緒にバージョン管理可能です。

FAQ（よくある質問）

Circle APIをテストするのにKYBは必要ですか？

いいえ。サンドボックスアカウントはEメールアドレスがあれば誰でも利用可能。KYBは本番環境で実際のドルを扱う場合のみ必須。サンドボックスには全チェーン用のUSDCファセットが付属。

Circle MintとCircle Walletsの違いは？

Circle Mintは機関投資家向けオンランプで、USD入金→USDC出金・逆も可。Wallets/W3Sはエンドユーザー向けカストディ/トランザクション基盤。一般的なアプリはWallets、財務用途はMintを利用。MoonPay APIガイドも参照。

CCTPはブリッジリスクをどう回避？

ソースチェーンでUSDCをバーンし、Circleの署名済みアテステーションでデスティネーションチェーンにミント。第三者ブリッジのバリデータやロック流動性プール不要。

鍵を保持せずにCircle Walletsを使える？

はい。W3SのUser-Controlled WalletsはMPCとPIN認証で、ユーザーがSDK経由で署名。開発者は秘密鍵に触れません。Developer-Controlled Walletsの場合はエンティティシークレットでバックエンド署名。

CircleはSolanaや非EVMチェーンをサポート？

はい。W3SはSolana、Aptos、NEAR、複数EVM L2をカバー。CCTP v2でSolanaサポート拡大、ネイティブUSDCがSolana/EVM間で自由に移動可能。

エンティティシークレットを安全にローテーションするには？

ダッシュボードから新シークレット生成＆登録。切り替え期間中は古い/新しい暗号文を並行運用。SDKは環境変数内のシークレットを自動検出するため、ローリングデプロイで対応可能です。

DEV Community