BlinkCodes catalog

BlinkCodes エージェントインターフェース

blinkcodes.com 用の機械可読なインターフェースです。blinkcodes.com は、メールで数秒以内に配信するギフトカードコード、サービスのトップアップ、旅行用 eSIM を販売するストアです。

ここに記載されているものはすべて、リモートのホスト型サービスです。インストールするものも、実行するサーバーもありません。クライアントから以下の URL に接続してください。このリポジトリは、これらのエンドポイントを文書化し、スキーマを固定し、実際に動作する例を提供するために存在します。

インターフェース	エンドポイント	仕様
MCP（カタログ＋購入）	https://blinkcodes.com/mcp	Streamable HTTP、プロトコル 2025-06-18
A2A	https://blinkcodes.com/a2a	JSON-RPC、プロトコル 0.3
x402（呼び出しごとの支払い）	https://blinkcodes.com/api/v1/buy	x402 v2（リクエストに応じて v1）、Base 上の USDC
OpenAPI	https://blinkcodes.com/openapi.json	x-payment-info（MPP）を含む
エージェント向けの平易な説明	https://blinkcodes.com/llms.txt

検出用ドキュメント：/.well-known/agent-card.json、 /.well-known/mcp/server-card.json、 /.well-known/api-catalog、 /.well-known/agent-skills/index.json、 /.well-known/acp.json、 /.well-known/ucp。

MCP サーバー

Official MCP Registry に com.blinkcodes/catalog として公開されています（server.json）。

ツールは 3 つあります。カタログ用ツール 2 つは読み取り専用で無料です。キー、アカウント、支払いは不要です。3 つ目は料金が発生し、x402 のみで利用できます。

ツール	用途
search_catalog	ギフトカード、トップアップ、eSIM プランを検索します。価格、在庫状況、商品 URL を返します。
get_product	ID で商品を 1 つ取得します。価格付きの額面、注文時に必要な入力項目、コードを引き換えられない国が返されます。
buy_product	購入して、商品を受け取ります。2 回の呼び出しで完了します。引数を渡すと x402 の支払い要件が返され、署名済みペイロードを渡すとコードが返されます。

buy_product は、以下の POST /api/v1/buy と同じ処理経路（検証、予約、決済、履行の順）で実行されます。そのため、MCP でストアを見つけたエージェントは、購入を完了するためにプロトコルを切り替える必要がありません。最初の呼び出しで料金が請求されることはなく、残り 2 つのツールの利用にウォレットは不要です。

リモート MCP に対応するクライアントに追加します。

{
  "mcpServers": {
    "blinkcodes": {
      "type": "http",
      "url": "https://blinkcodes.com/mcp"
    }
  }
}

ツールの完全なスキーマと curl の実行記録については、docs/mcp.md を参照してください。

stdio のみに対応するクライアントでは、同じホスト型エンドポイントにプロキシする Dockerfile のブリッジを使用できます。

docker build -t blinkcodes-mcp . && docker run -i --rm blinkcodes-mcp

クライアントがリモート MCP に対応している場合は、上記の直接 URL を優先してください。ブリッジを使うと経由先が増えるだけで、利点はありません。

エージェント向けの購入

支払いは x402 を介した Base 上の USDC です。1 つのエンドポイントで 2 回のリクエストを行います。

1. 注文内容を本文に含めて POST /api/v1/buy を送信すると、対象商品の価格が設定された支払い要件と、order ブロック（ID、アクセストークン、ステータス URL）を含む 402 が返ります。
2. 同一のリクエストに PAYMENT-SIGNATURE ヘッダーを付けて送信すると、コードを含む 200 が返ります。同期処理の時間枠を超えて商品の引き渡しに時間がかかる場合は、status_url を含む 202 が返ります。

// the body, in both passes
{
  "email": "[email protected]",
  "product_type": "giftcard",   // giftcard | topup | esim | phone_rental
  "product_id": 187,
  "item_id": 1195,
  "quantity": 1
}

• ネットワークは eip155:8453、資産は 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913（USDC）です。
• デフォルトでは x402 v2 を使用します。v1 クライアントは X-PAYMENT を送信するか、X-PAYMENT-VERSION: 1 を指定して v1 の見積もりを取得してください。
• GET /api/v1 では決済手段の説明を無料で取得できます。
• 商品名を何も指定せずに /api/v1/buy を呼び出すと、決済手段の最低価格を提示する 402 が返り、注文は作成されません。クローラーでも安全に使える確認用の形式です。

実行例：examples/x402-buy.mjs。決済手段、最低価格、支払い可能なコインのペアについては、GET /api/public/payment-methods を参照してください。

A2A

エージェントカードは /.well-known/agent-card.json にあり、JSON-RPC の message/send は https://blinkcodes.com/a2a で利用できます。スキルは、カタログの 2 つのツールと buy_product です。このトランスポートでは、buy_product は支払い拡張機能 a2a-x402（https://github.com/google-a2a/a2a-x402/v0.1）を使用します。カタログのスキルは無料のため、required: false と宣言されています。

見積もりを取得すると x402.payment.required を含む input-required の Task が返ります。支払う際は、同じ taskId に x402.payment.payload を含めて送信すると、引き渡し内容をアーティファクトとして含む completed の Task が返ります。詳しくは examples/a2a.sh を参照してください。

人間向けのドキュメント

ストア、価格、利用規約については https://blinkcodes.com をご覧ください。サポート窓口：[email protected]。

ライセンス

MIT — このリポジトリ内のドキュメントとサンプルに適用されます。サービス自体には、サイトに掲載されている利用規約が適用されます。