Blog

Circle APIでUSDCを取引する方法

Mark Ponomarev

Mark Ponomarev

23 6月 2025

Circle APIでUSDCを取引する方法

USDコイン（USDC）は、安定性と信頼性の要として台頭してきました。全額準備金に裏打ちされたドルペッグのステーブルコインとして、USDCは従来の法定通貨と成長著しいデジタル資産の世界との間のギャップを埋めます。これは、米ドルの価格安定性を維持しつつ、暗号通貨の速度とグローバルな到達範囲を提供するため、インターネット上での商取引、トレーディング、送金に理想的な媒体となります。

USDCエコシステムの中心にあるのは、このステーブルコインの主要開発元であるCircleです。Circleは、開発者や企業がUSDCをアプリケーションにシームレスに統合できるようにする一連のAPIを提供しています。特にCircle Mint APIは、新しいUSDCのミント（発行）、法定通貨への換金、および多数のサポートされているブロックチェーン間での転送のための強力なゲートウェイを提供します。これは、公開市場での価格変動を投機するという意味での「取引」ではなく、より根本的なものです。すなわち、プログラムによって価値を移動させ、従来の金融経路からデジタル世界へオンランプし、再びオフランプする能力です。

本記事は、USDC取引のためのCircle APIを習得するための包括的なガイドです。開発者アカウントの初期設定から、複雑な転送や支払いの実行まで、詳細な旅に出かけます。以下の内容を扱います。

このガイドの終わりには、安定した、グローバルで、プログラム可能なデジタルドルの力を活用する洗練されたアプリケーションを構築するために必要な知識と実践的な例が身についているでしょう。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

最大限の生産性で開発チームが協力できる統合されたオールインワンプラットフォームをお探しですか？

Apidogは、お客様のすべての要求に応え、Postmanをはるかに手頃な価格で置き換えます！
ボタン

Circleを始める

コードを一行も書く前に、開発環境をセットアップし、資格情報を取得する必要があります。この基礎的なステップは、スムーズな統合プロセスにとって非常に重要です。

サンドボックス環境 vs. 本番環境

CircleはAPI用に2つの異なる環境を提供しています：サンドボックスと本番環境です。それらの役割を理解することが、成功し安全な統合への第一歩です。

各環境のAPIホストは以下の通りです。

環境 APIホストURL
サンドボックス https://api-sandbox.circle.com
本番環境 https://api.circle.com

このガイド全体を通して、すべての例はサンドボックスURLを使用します。これは重要なベストプラクティスです: 常に最初にサンドボックス環境で開発およびテストを行ってください。

サンドボックスアカウントの作成

サンドボックス環境へのアクセスを可能にするCircle開発者アカウントを作成することから、あなたの旅は始まります。

  1. Circleウェブサイトへ移動: 公式のCircle開発者ページにアクセスしてください。
  2. サインアップ: 開発者またはサンドボックスアカウントのサインアップオプションを探してください。メールアドレスや安全なパスワードなどの基本的な情報を提供する必要があります。
  3. メールアドレスの確認: サインアップフォームを送信した後、確認メールが届きます。このメール内のリンクをクリックしてアカウントを有効化してください。
  4. ダッシュボードへのアクセス: アカウントが確認されたら、開発者ダッシュボードにログインできます。このダッシュボードは、アプリケーション、APIキーの管理、サンドボックスアクティビティの表示のための中心的なハブです。

最初のAPIキーの生成

APIキーは、Circle APIへのアプリケーションのリクエストを認証するユニークな秘密トークンです。これは、リクエストがあなたから発信されたものであり、不正な第三者からではないことを証明します。

新しいサンドボックスダッシュボードからAPIキーを生成する方法は次のとおりです。

  1. Circle開発者サンドボックスアカウントにログインします。
  2. APIキーセクションへ移動: ダッシュボードで、「APIキー」または「開発者設定」と表示されたセクションを見つけてください。
  3. 新しいキーの作成: 「新しいAPIキーを作成」というオプションがあります。それをクリックします。
  4. キーに名前を付ける: キーに説明的な名前を付けてください（例：「My Trading App - Test」）。これにより、特に異なるアプリケーション用に複数のキーを持っている場合に、後でキーの目的を特定しやすくなります。
  5. キーをコピーして安全に保管する: 作成後、APIキーが画面に表示されます。完全なキーが表示されるのはこの時だけです。すぐにコピーし、パスワードマネージャーやプロジェクトの環境変数ファイルなど、安全な場所に保管してください。ソースコードにAPIキーを直接ハードコードしないでください。

あなたのAPIキーは機密情報です。それを持っている人は誰でも、あなたのアカウントに代わってリクエストを行うことができます。パスワードと同じレベルのセキュリティで扱ってください。

認証と初期設定

APIキーを手に入れたら、Circle APIへの最初の呼び出しを行う準備ができました。最初のステップは、認証プロセスを習得し、すべてが正しく設定されていることを確認するために接続をテストすることです。

API認証：ベアラートークン

Circle APIは、ベアラートークン認証スキームを使用します。これは、すべてのAPIリクエストにAPIキーを含むAuthorizationヘッダーを含める必要がある標準的なHTTP認証方法です。

ヘッダー形式は次のとおりです：Authorization: Bearer YOUR_API_KEY

YOUR_API_KEYは、前の章で生成した実際の秘密キーに置き換える必要があります。

接続のテスト

複雑なトランザクションに深く入る前に、2つの簡単なテストを実行することが不可欠です。1つはCircle APIサーバーへの基本的なネットワーク接続を確認するため、もう1つはAPIキーが正しく設定されていることを確認するためです。

/pingによる生の接続テスト

/pingエンドポイントはシンプルなヘルスチェックです。認証は不要で、Circle APIサーバーに到達できることを確認するために使用されます。

HTTPリクエストを行うための一般的なコマンドラインツールであるcURLを使用して呼び出す方法は次のとおりです。

curl -H 'Accept: application/json' \
  -X GET --url https://api-sandbox.circle.com/ping

成功時の応答:

接続が成功すると、APIはシンプルなJSONオブジェクトを返します。

{
  "message": "pong"
}

この応答を受け取った場合、サンドボックス環境への接続が正常に確立されています。そうでない場合は、ネットワーク接続、ファイアウォール、またはURLのタイプミスを確認してください。

/v1/configurationによるAPIキーのテスト

次に、APIキーが有効で適切にフォーマットされているかテストしましょう。/v1/configurationエンドポイントは、アカウントの基本的な設定情報を取得し、認証が必要です。

cURLコマンドは次のとおりです。${YOUR_API_KEY}を実際のAPIキーに置き換えることを忘れないでください。セキュリティのため、環境変数を使用することをお勧めします。

# It's best practice to store your API key in an environment variable
# export YOUR_API_KEY='YOUR_KEY_HERE'

curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/configuration

成功時の応答:

成功したリクエストは、マスターウォレットIDを含むJSONオブジェクトを返します。masterWalletIdは、資金が保持されているあなたのアカウントに関連付けられたプライマリウォレットの一意の識別子です。

{
  "data": {
    "payments": {
      "masterWalletId": "1234567890"
    }
  }
}

エラー時の応答:

APIキーまたはAuthorizationヘッダーのフォーマットに問題がある場合、401 Unauthorizedエラーが返されます。

{
  "code": 401,
  "message": "Malformed authorization. Are the credentials properly encoded?"
}

このエラーが表示された場合は、以下を再確認してください。

よりシンプルな統合のためのCircle SDKの使用

HTTPリクエストを使用してAPIと直接やり取りすることもできますが、CircleはNode.js、Python、Javaなどの人気のあるプログラミング言語向けにソフトウェア開発キット（SDK）を提供しています。これらのSDKは、認証、リクエストのフォーマット、応答の解析のためのボイラープレートコードを処理し、開発プロセスをより迅速かつエラーを起こしにくくします。

Circle Node.js SDKを初期化する方法の簡単な例を以下に示します。

// Install the SDK first: npm install @circle-fin/circle-sdk

import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
  process.env.CIRCLE_API_KEY, // API key from environment variable
  CircleEnvironments.sandbox   // Pointing to the sandbox environment
);

async function getConfiguration() {
  try {
    const response = await circle.core.getConfiguration();
    console.log(response.data.payments.masterWalletId);
  } catch (error) {
    console.error(error.response.data);
  }
}

getConfiguration();

SDKを使用すると、低レベルの詳細が抽象化され、アプリケーションのビジネスロジックに集中できます。どのような本格的なプロジェクトでもSDKを使用することをお勧めします。

主要概念とAPIリソース

Circle APIを効果的に使用するには、その基盤となるデータモデルを理解する必要があります。APIは、支払い、ウォレット、転送など、システム内の主要なエンティティを表すJSONオブジェクトである一連のリソースを中心に構築されています。

APIリソースの概要

Circleのリソースはいくつかのグループに分類できます。

主要リソース: これらは、実行できる主要な金融アクションを表します。

方法と手段:

ネストされたリソース: これらは、詳細情報を提供するために他のリソース内に埋め込まれることが多いオブジェクトです。

詳細解説: Paymentオブジェクト

paymentは、資金を受け取る方法です。APIはカード支払いをサポートしていますが、USDCのユースケースでは、Circleウォレットに資金を供給する支払いを扱うことが多くなります。

Paymentオブジェクトの例:

{
  "id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
  "type": "payment",
  "merchantId": "c680d087-7b41-40aa-95a2-68febcdddb22",
  "merchantWalletId": "1000002853",
  "amount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "source": {
    "id": "86461e9f-db1a-487f-915b-641138062e7c",
    "type": "card"
  },
  "description": "New customer payment",
  "status": "confirmed",
  "fees": {
    "amount": "0.58",
    "currency": "USD"
  },
  "createDate": "2024-01-10T02:29:53.888Z",
  "updateDate": "2024-01-10T02:32:19.421Z"
}

主要属性:

詳細解説: Transferオブジェクト

transferは、USDCを「取引」または移動させる上で最も重要なオブジェクトと言えるでしょう。これはデジタル通貨の移動を表します。

Transferオブジェクトの例:

{
  "id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
  "source": {
    "type": "wallet",
    "id": "1000002853"
  },
  "destination": {
    "type": "blockchain",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "chain": "ETH"
  },
  "amount": {
    "amount": "150.50",
    "currency": "USD"
  },
  "status": "pending",
  "createDate": "2024-05-15T18:44:03.484Z",
  "updateDate": "2024-05-15T18:44:03.484Z"
}

主要属性:

ソースおよびデスティネーションオブジェクト

これらのネストされたオブジェクトは、あらゆるトランザクションにおける資金の流れを定義するため、非常に重要です。

それらのtypeフィールドは、ソースまたはデスティネーションの種類を決定します。

サポートされるチェーンと通貨

Circleはチェーンに依存せず、常にサポートを拡大しています。2024年後半現在、USDCは以下の多数の主要なブロックチェーンで利用可能です。

送金を行う際には、正しいchain識別子を指定する必要があります。法定通貨の場合、APIは主にUSDとEURをサポートしています。USDCの送金を扱う場合、Moneyオブジェクトのcurrencyは常にUSDに設定する必要があります。

トランザクションの実行：完全なライフサイクル

さて、本題に入ります。APIを使用して資金を移動させることです。法定通貨をオンランプしてUSDCを取得し、そのUSDCを外部アドレスに転送し、最後に法定通貨の銀行口座にオフランプするという完全なライフサイクルを順に見ていきます。

ステップ1: Paymentによる法定通貨のオンランプ

多くのアプリケーションにとって、最初のステップは顧客からの法定通貨をCircleウォレット内のUSDCに変換することです。これにはCreate Payment APIエンドポイントが使用されます。APIは様々な支払いソースをサポートしていますが、ここではその概念に焦点を当てます。

顧客があなたに500ドルを支払うと仮定しましょう。/v1/paymentsに対してPOSTリクエストを行います。

支払い作成のためのAPIリクエスト:

curl -X POST \
  https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "your-unique-uuid-here-for-payment",
        "source": {
          "id": "some-card-or-bank-id",
          "type": "card"
        },
        "amount": {
          "amount": "500.00",
          "currency": "USD"
        },
        "description": "Payment for services rendered"
      }'

重要事項: ここでidempotencyKeyが非常に重要です。これは、このリクエストのためにあなたが生成するユニークなID（UUID形式）です。同じリクエストを2回送信した場合（例：ネットワークエラーのため）、Circleはそのキーを認識し、支払いを一度だけ処理します。これについては次の章で詳しく説明します。

この支払いが処理され、そのstatusがconfirmed（確認済み）またはpaid（支払い済み）になると、同額のUSDC（手数料を差し引いた額）があなたのmerchantWalletIdにクレジットされます。

ステップ2: ウォレット残高の確認

支払いを受け取った後、資金が到着したことを確認したいでしょう。どのウォレットの残高でも確認できますが、最も一般的なのはマスターウォレットです。

残高取得のためのAPIリクエスト:

curl -X GET \
  https://api-sandbox.circle.com/v1/wallets/${YOUR_WALLET_ID}/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

${YOUR_WALLET_ID}を、以前取得したmasterWalletIdに置き換えてください。

API応答:

応答は、あなたが保有する各通貨の残高のリストになります。

{
  "data": {
    "available": [
      {
        "amount": "495.50",
        "currency": "USD"
      }
    ],
    "unsettled": [
      {
        "amount": "0.00",
        "currency": "USD"
      }
    ]
  }
}

available残高は、すぐに転送または支払い（ペイアウト）できる金額です。

ステップ3: USDCのオンチェーン転送

これがUSDCを使用する上での核心です。ウォレットからサポートされているブロックチェーン上の任意の外部アドレスに資金を転送できます。これは、サプライヤーへの支払い、DeFiプロトコルへの資金移動、またはユーザーへの価値の送信に最適です。

イーサリアムアドレスに100 USDCを送金したいと仮定しましょう。

転送作成のためのAPIリクエスト:

curl -X POST \
  https://api-sandbox.circle.com/v1/transfers \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "another-unique-uuid-for-transfer",
        "source": {
          "type": "wallet",
          "id": "1000002853"
        },
        "destination": {
          "type": "blockchain",
          "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
          "chain": "ETH"
        },
        "amount": {
          "amount": "100.00",
          "currency": "USD"
        }
      }'

リクエストボディの内訳:

APIは、最初はpending（保留中）のstatusを持つTransferオブジェクトを返します。

ブロックチェーンの確認の理解

オンチェーントランザクションは即時ではありません。転送はネットワークにブロードキャストされ、その後マイナーまたはバリデーターによって確認される必要があります。転送のstatusは、ブロックチェーン上で十分な数の確認を受け取った後にのみcomplete（完了）に変わります。Circleがこの複雑さを管理します。GET /v1/transfers/{id}エンドポイントをポーリングするか、または（次の章で説明する）ウェブフックを使用して、転送が完了したときに通知を受け取ることで、ステータスを追跡できます。

ステップ4: PayoutによるUSDCから法定通貨へのオフランプ

ライフサイクルの最終ステップは、USDCを銀行口座の法定通貨に変換することです。これはpayout（支払い）を介して行われます。支払いを作成する前に、まず銀行口座をリンクして確認する必要があります。これによりWire Accountオブジェクトが作成されます。

送金先の銀行口座が設定されている（その独自のidがある）場合、支払いを作成できます。

支払い作成のためのAPIリクエスト:

curl -X POST \
  https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "yet-another-unique-uuid-for-payout",
        "destination": {
          "type": "wire",
          "id": "your-bank-account-uuid-here"
        },
        "amount": {
          "amount": "250.00",
          "currency": "USD"
        }
      }'

APIはPayoutオブジェクトを返します。statusは最初はpending（保留中）であり、資金が送金先の銀行に正常に送られた後にcomplete（完了）に移行します。

高度な機能とベストプラクティス

真に堅牢でスケーラブルなアプリケーションを構築するには、基本的なAPI呼び出しを超えて、Circleが提供する高度な機能を活用する必要があります。これらの機能は、データ整合性を確保し、リアルタイムの更新を提供し、アプリケーションを回復力のあるものにするために設計されています。

冪等なリクエスト：二重支払いの防止

idempotencyKeyについては何度か触れてきましたが、その重要性はいくら強調してもしすぎることはありません。金融システムでは、誤って操作を2回実行すること（支払いまたは転送の送信など）は壊滅的な結果を招く可能性があります。ネットワークの問題により、サーバーが正常に処理した場合でもリクエストがタイムアウトする可能性があります。冪等性がない場合、アプリケーションは自動的にリクエストを再試行し、重複したトランザクションを引き起こす可能性があります。

仕組み:

これにより、特定のリクエストが何回送信されても、一度しか実行されないことが保証されます。

ベストプラクティス: すべてのPOST操作に対して、常にidempotencyKeyを生成して送信してください。

ウェブフックによるリアルタイム更新

トランザクションのステータスを確認するためにAPIを繰り返しポーリングする（GET /v1/transfers/{id}）ことは、非効率的で遅いです。正しい現代的なアプローチは、ウェブフックを使用することです。

ウェブフックは、特定のイベントが発生したときに、あるアプリケーション（Circle）から別のアプリケーション（あなたのアプリケーション）に送信される自動メッセージです。これらの通知を受け取りたいURLをCircleダッシュボードで設定できます。

支払い、転送、またはペイアウトのステータスが変更されると、Circleは設定されたURLに、更新されたオブジェクトを含む通知ペイロードを伴うPOSTリクエストを送信します。

完了した転送の通知ペイロード例:

{
  "notification": {
    "id": "notification-uuid",
    "type": "transfers",
    "subscriptionId": "your-subscription-id"
  },
  "transfer": {
    "id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
    "source": { ... },
    "destination": { ... },
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "status": "complete",
    "transactionHash": "0x123abc...",
    "createDate": "2024-05-15T18:44:03.484Z",
    "updateDate": "2024-05-15T18:48:12.123Z"
  }
}

これらの通知をリッスンすることで、アプリケーションは転送の完了や支払いの失敗といったイベントに即座に反応でき、はるかに優れたユーザーエクスペリエンスを提供し、リアルタイムの自動化を可能にします。

ページネーションとフィルタリング：大規模データセットの処理

アプリケーションが成長するにつれて、数千もの支払い、転送、その他のレコードが蓄積されます。/v1/transfersのようなGETエンドポイントを使用してそれらすべてを一度にリクエストすると、遅く扱いにくくなります。

Circle APIは、これを解決するためにカーソルベースのページネーションを使用します。リソースをリスト表示すると、応答には限られた数のアイテム（「ページ」）のみが含まれます。このページのサイズはpageSizeパラメータで制御できます。結果の次または前のページを取得するには、pageAfterまたはpageBeforeパラメータを使用し、表示した最後のアイテムまたは最初のアイテムのIDを渡します。

例: 20件の転送の最初のページを取得する:
GET /v1/transfers?pageSize=20

例: 20件の転送の次のページを取得する:
GET /v1/transfers?pageSize=20&pageAfter={id_of_last_transfer_from_previous_page}

時間範囲（fromおよびtoタイムスタンプ）やその他のリソース固有の属性に基づいて結果をフィルタリングすることもできます。

エラー処理：回復力のあるアプリケーションの構築

物事はうまくいかないこともありますし、実際にうまくいかなくなるでしょう。APIリクエストは、無効な入力、資金不足、または一時的なサーバーの問題により失敗する可能性があります。堅牢なアプリケーションは、これらのエラーを予測し、適切に処理する必要があります。

Circle APIは、リクエストの結果を示すために標準的なHTTPステータスコードを使用します。

エラーが発生した場合、API応答ボディには詳細情報を含むJSONオブジェクトが含まれます。

エラー応答例 (400 Bad Request):

{
  "code": 2,
  "message": "Invalid or missing parameter. See details for more information.",
  "errors": [
    {
      "location": "body",
      "message": "destination address is invalid",
      "param": "destination.address"
    }
  ]
}

API呼び出しからの潜在的な例外を処理するために、コードは常にtry/catchブロック（または使用する言語の同等のもの）で囲む必要があります。エラーの詳細をログに記録し、適切であれば、ユーザーに役立つメッセージを表示すべきです。

結論：金融の未来を強化する

USDCで取引するためのCircle APIの使用の全プロセスを旅してきました。初期サンドボックスの設定と認証から、支払い、転送、ペイアウトの実行まで、強力な金融アプリケーションを構築するための基礎知識を身につけました。また、プロフェッショナルな本番環境対応システムを構築するために不可欠な、冪等性、ウェブフック、エラー処理といった高度な機能についても探求しました。

Circle APIは、デジタル通貨を移動させるだけでなく、新しいインターネットネイティブな金融システムのためのプログラム可能なレールを提供します。ブロックチェーン技術の複雑さを抽象化し、クリーンでリソース指向のAPIを提供することで、Circleは開発者がイノベーションを起こし、次世代のグローバルコマース、金融サービス、ピアツーピア決済を構築する力を与えます。

可能性は無限大です。ツールはあなたの手の中にあります。さあ、素晴らしいものを構築しましょう。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

最大限の生産性で開発チームが協力できる統合されたオールインワンプラットフォームをお探しですか？

Apidogは、お客様のすべての要求に応え、

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

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

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