SingIt x402

Sign402 Gateway

Hermes Sign402 用の統合ローカル Mac ゲートウェイです。

以下を組み合わせています。

• Firefly によるポリシー承認；
• Firefly による支払い承認；
• Algorand TestNet 上でのローカル支払い実行。

Hermes が受け取るのは公開トンネル URL だけで、秘密鍵を受け取ることはありません。

実装に関する注意：/approve-policy は Firefly の PAYMENT=<policyHash> 承認パスを使用します。現在のテスト端末では、以前の POLICY=<policyHash> ファームウェアコマンドは承認後にデバイスが応答しなくなる場合がありますが、PAYMENT=<hash> は安定して承認フローに戻ります。

支払いコンテキストが利用可能な場合、支払いの承認には Firefly の PAYMENT-CONTEXT=<line1>|<line2>|<line3> プレコマンドを使用します。現在の GoPlausible デモでは、次のように表示されます。

x402 WEATHER
0.01 USDC
GoPlausible API
Hash ....a1ef
OK / CANCEL

エンドポイント

GET  /health
POST /approve-policy
POST /approve-payment
POST /execute-payment
GET  /events/latest
POST /events/latest
POST /agent/buy-probe
GET  /agent/tools
POST /agent/inspect-tool
POST /agent/buy-tool
POST /agent/inspect-x402
POST /agent/buy-x402
POST /agent/inspect-llm-credits-topup
POST /agent/top-up-llm-credits
POST /agent/wallet
POST /agent/create-wallet
POST /agent/wallet-balance

/agent/inspect-x402 と /agent/buy-x402 は、現在、次の 2 つの公式 x402 レーンに対応しています。

• 既存の x402-avm 支払い署名ビルダーを使用する Algorand TestNet。
• ../cdp-x402-service、CDP API キーウォレット、CDP ファシリテーターを使用する Base Mainnet。

SINGIT で資金を供給する Bankr LLM クレジット

ゲートウェイを使用して、Hermes が SINGIT などのプロジェクトトークンで Bankr LLM Gateway のクレジットに資金を供給することもできます。これは x402 Cloud の支払いではなく、別個のチャージフローです。

SINGIT spending policy -> Firefly top-up approval -> bankr llm credits add <usd> --token <SINGIT> --yes

まず、SINGIT の予算ポリシーを承認します。

{
  "policy": {
    "version": "1",
    "agentId": "hermes-demo",
    "policyId": "policy-singit-llm-001",
    "allowedPurpose": "bankr_llm_credits_topup",
    "asset": "0xc2c1e0b7C401e6217193732272444D928646eba3",
    "maxBudgetAtomic": "10000000000000000000000",
    "maxPerPaymentAtomic": "5000000000000000000000",
    "nonce": "singit-llm-credits-001"
  }
}

実行前にチャージ内容を確認します。

curl -sS -X POST http://127.0.0.1:8099/agent/inspect-llm-credits-topup \
  -H "Content-Type: application/json" \
  -d '{
    "creditAmountUsd": "5",
    "fundingTokenAddress": "0xc2c1e0b7C401e6217193732272444D928646eba3",
    "fundingTokenSymbol": "SINGIT",
    "maxFundingTokenAmountAtomic": "5000000000000000000000"
  }'

次に、返された topUpIntent を使ってチャージを実行します。

curl -sS -X POST http://127.0.0.1:8099/agent/top-up-llm-credits \
  -H "Content-Type: application/json" \
  -d '{
    "creditAmountUsd": "5",
    "fundingTokenAddress": "0xc2c1e0b7C401e6217193732272444D928646eba3",
    "fundingTokenSymbol": "SINGIT",
    "maxFundingTokenAmountAtomic": "5000000000000000000000",
    "topUpIntent": "bankr-llm-..."
  }'

ゲートウェイは、保存済みのポリシーが SINGIT トークンアドレスおよび bankr_llm_credits_topup の目的に一致することを確認し、Firefly にチャージ内容への正確な承認を求めてから Bankr CLI を呼び出します。bankr が PATH にない場合は、SIGN402_BANKR_CLI を設定してください。SINGIT トークンアドレスのデフォルト値は 0xc2c1e0b7C401e6217193732272444D928646eba3 です。必要に応じて SIGN402_SINGIT_TOKEN_ADDRESS で上書きしてください。

Base ウォレット管理 MVP

ホスト型 Telegram ボットは、Telegram ユーザーごとに 1 つの Base エージェントウォレットを作成できます。 このウォレットはカストディアル方式で、少額のエージェント予算のみを対象としています。iMessage 承認プロバイダーとユーザーごとの支出上限が実装されるまでは、支出は無効のままです。

必要なサーバーシークレットを生成します。

python3 - <<'PY'
from cryptography.fernet import Fernet
import secrets

print("SIGN402_WALLET_MASTER_KEY=" + Fernet.generate_key().decode())
print("SIGN402_WALLET_API_TOKEN=" + secrets.token_urlsafe(32))
PY

ゲートウェイサービスの環境に設定します。

SIGN402_WALLET_MASTER_KEY=...
SIGN402_WALLET_API_TOKEN=...
SIGN402_USER_WALLET_STORE_PATH=<STATE_DIR>/user-wallets.db

ウォレット API トークンは、ローカルホストでも必須です。Hermes または信頼できるローカルアダプターは、次の情報を付けてウォレットエンドポイントを呼び出す必要があります。

Authorization: Bearer <SIGN402_WALLET_API_TOKEN>

エージェント向けエンドポイント：

POST /agent/wallet
POST /agent/create-wallet
POST /agent/wallet-balance

例：

curl -sS -X POST http://127.0.0.1:8099/agent/create-wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SIGN402_WALLET_API_TOKEN" \
  -d '{"telegramUserId":"<telegram-id>","telegramUsername":"<telegram-username>"}'

レスポンスに秘密鍵の情報が含まれることはありません。暗号化されたウォレットデータベースは、制限付きアクセス権限を設定した VPS ファイルシステム上に保持してください。ゲートウェイはウォレットディレクトリを 0700、SQLite データベースを 0600 で作成します。

Base ウォレットの残高

ホスト型ウォレットの残高を確認するには、Base Mainnet のプライベート JSON-RPC エンドポイントを明示的に指定する必要があります。標準的な Base Mainnet RPC であればどれでも使用できます。推奨は Coinbase Developer Platform の CDP Node RPC エンドポイントです。

SIGN402_BASE_RPC_URL=https://api.developer.coinbase.com/rpc/v1/base/<client-api-key>

Alchemy の Base Mainnet エンドポイントも使用でき、Alchemy Token API を介して他の ERC-20 残高を自動検出する機能も有効になります。これは任意です。

API キーが含まれるため、RPC URL 全体をシークレットとして扱ってください。Hermes のプロンプト、Telegram、スクリーンショット、リポジトリファイル、共有ログには記載しないでください。ホスト型残高プロバイダーは、公開されているレート制限付き Base エンドポイントに暗黙的にフォールバックすることはありません。

/agent/wallet-balance は常に Base Mainnet の ETH、正規の USDC、SINGIT を読み取ります。エンドポイントが Alchemy の場合は、Alchemy Token API を介して、残高が 0 ではない追加の ERC-20 トークンを最大 10 個まで自動検出します。それ以外の RPC では、読み取る ERC-20 トークンを指定するために SIGN402_BASE_BALANCE_TOKENS を設定します。

SIGN402_BASE_BALANCE_TOKENS=SYMBOL:0xaddress:decimals,SYMBOL2:0xaddress2:decimals2

カンマ区切りで最大 10 件まで指定できます。追加トークンには未検証のラベルとコントラクトアドレスが表示され、表示専用として扱われます。リストに追加しても、エージェントにそれらのトークンを使用する権限が与えられることはありません。

上記の CDP Node RPC URL は eth_getLogs が必要な SIGN402_ALLOWANCE_RPC_URL にも使用できます。公開されている https://mainnet.base.org エンドポイントでは、このメソッドは拒否されます。

ゲートウェイの実行

インストール、起動、テストについては、運用ガイドを参照してください。以前のローカルデモサーバー、ダッシュボード、ランチャーは廃止されました。保守されている Graph/Ledger デモについては、実行手順書を参照してください。

Base Mainnet CDP フロー

CDP ヘルパーを一度セットアップします。

cd cdp-x402-service  # from the repo root
npm install
cp .env.example .env
npm run account

npm run account を実行する前に、ローカルの CDP シークレットを .env に入力してください。実際に購入する前に、表示された購入者の EVM アドレスに Base Mainnet USDC を入金してください。

ローカルの Base x402 セラーを起動します。

npm run serve

デフォルトの保護対象リソース：

http://127.0.0.1:4021/paid/sign402-report

/approve-policy から Base ポリシーを承認します。

{
  "policy": {
    "version": "1",
    "agentId": "hermes-demo",
    "policyId": "policy-base-usdc-001",
    "allowedPurpose": "x402_api_access",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bDa02913",
    "maxBudgetAtomic": "100000",
    "maxPerPaymentAtomic": "10000",
    "nonce": "base-mainnet-usdc-001"
  }
}

次に、同じエージェント向けフローで Base の有料ツールを確認して購入します。

curl -sS -X POST http://127.0.0.1:8099/agent/inspect-tool \
  -H "Content-Type: application/json" \
  -d '{"tool":"base.sign402.report"}'

curl -sS -X POST http://127.0.0.1:8099/agent/buy-tool \
  -H "Content-Type: application/json" \
  -d '{"tool":"base.sign402.report"}'

ゲートウェイで使用できるエイリアス：base-report、sign402-report、get_sign402_report。

ゲートウェイは引き続き保存済みポリシーを確認し、CDP の購入者を呼び出す前に Firefly の承認を要求します。デバッグ用に、生の URL エンドポイントも引き続き利用できます。

curl -sS -X POST http://127.0.0.1:8099/agent/buy-x402 \
  -H "Content-Type: application/json" \
  -d '{"url":"http://127.0.0.1:4021/paid/sign402-report"}'

手動実行

決済エグゼキューターの venv に、追加の依存関係を 1 つだけインストールします。

../payment-executor/.venv/bin/python -m pip install pyserial

Firefly のポートを確認します。

ls /dev/cu.usb*

ゲートウェイを起動します。

cd sign402-gateway  # from the repo root
FIREFLY_PORT=/dev/cu.usbmodemXXXX ../payment-executor/.venv/bin/python -m sign402_gateway

デフォルト URL：

http://127.0.0.1:8099

ウォレットネイティブな Bitrefill チェックアウト

Telegram／一般消費者向けの購入では、この方式を本番のチェックアウトとして使用します。

Hermes/Telegram -> Sign402 Gateway -> Bitrefill eCommerce MCP -> Base USDC payment -> protected redemption

ユーザー／埋め込みウォレットが購入資金を SINGIT で用意し、設定済みの CDP ウォレットが USDC にスワップしてから、ゲートウェイが MCP 発行の Base 請求書を支払います。

ローカルの本番環境用ファイルを作成します。

cd sign402-gateway  # from the repo root
cp .env.wallet-bitrefill.example .env.wallet-bitrefill

以下を入力します。

BITREFILL_API_KEY=...
FIREFLY_PORT=/dev/cu.usbmodemXXXX

本番環境でのカタログ、見積もり、購入、請求書ステータスのリクエストには、Bitrefill MCP の https://api.bitrefill.com/mcp/<BITREFILL_API_KEY> を使用します。キーを含む URL は MCP クライアント内でのみ構築され、表示時には伏せられます。Bitrefill REST へのフォールバックはありません。別の互換性のある HTTPS エンドポイントを使用するには、 SIGN402_BITREFILL_MCP_URL に API キーのサフィックスを除いたベース URL を設定します。

カタログの閲覧には、永続化される 10 分間の stale-while-revalidate キャッシュを使用します。国ごとのスナップショット 1 つで、すべてのカテゴリーのフィルターとページをローカルで提供します。新しいスナップショットまたは古いスナップショットがあれば、すぐに返します。古いスナップショットの場合はバックグラウンドで 1 回だけ更新し、更新に失敗しても、最後に取得できた公開カタログを保持します。商品詳細、パッケージ価格、在庫確認、請求書、購入、支払い、フルフィルメント、引き換えデータでは、このキャッシュを常に迂回し、ライブの MCP リクエストを使用します。

シークレットではないカタログ設定は次のとおりです。

SIGN402_BITREFILL_CATALOG_CACHE_TTL_SECONDS=600
SIGN402_BITREFILL_CATALOG_TIMEOUT_SECONDS=8
SIGN402_BITREFILL_CATALOG_CACHE_PATH=~/.sign402/bitrefill-catalog-cache.json

永続ファイルには、正規化された公開商品一覧のメタデータのみが含まれます。ファイルサイズには上限があり、ユーザーのみがアクセスできる権限でアトミックに書き込まれます。また、Bitrefill キー、受取人データ、請求書、購入応答、商品詳細の価格、引き換え値が含まれることはありません。

ウォレットネイティブモードでゲートウェイを起動します。

cd sign402-gateway  # from the repo root
./scripts/run-wallet-bitrefill.sh

Bitrefill キーがすでに別のローカル環境ファイルにある場合は、シークレットをコピーせず、そちらを再利用します。

SIGN402_ENV_FILE="/path/to/your/existing.env" ./scripts/run-wallet-bitrefill.sh

このスクリプトでは、チェックアウトに重要な次のモードを設定します。

SIGN402_BITREFILL_MODE=live
SIGN402_BITREFILL_MCP_URL=https://api.bitrefill.com/mcp
SIGN402_BITREFILL_PAYMENT_METHOD=usdc_base
SIGN402_BITREFILL_USDC_TREASURY_MODE=cdp_wallet
SIGN402_BITREFILL_PRICING_SOURCE=cdp_wallet
SIGN402_BITREFILL_FUNDING_MODE=cdp_wallet_swap

SIGN402_BITREFILL_PAYMENT_METHOD=usdc_base の場合、設定済みの CDP または Bankr のトレジャリーが承認済みの正確な金額を送金する前に、MCP の請求書支払い要件が Base Mainnet 上の USDC として検証されます。balance の場合、Bitrefill は BITREFILL_API_KEY に関連付けられた残高を使用し、トレジャリーからの送金は行われません。既存の Firefly による承認、見積もりの有効期限、購入上限、リプレイ保護、注文の永続化は引き続き MCP の購入を保護します。

自動テストでは MCP の応答を注入して使用し、購入は一切行いません。実際の少額購入によるスモークテストは、ライブの上限とトレジャリー残高を確認したうえで、ユーザーの明示的な確認を得て、手動でのみ実行してください。

Bitrefill の商品を見積もります。

curl -sS -X POST http://127.0.0.1:8099/agent/quote-bitrefill \
  -H "Content-Type: application/json" \
  -d '{"productId":"bitrefill-giftcard-usd","packageId":"0.1","country":"US"}'

ユーザーの明示的な確認を得た後、ウォレットネイティブなチェックアウトを実行します。

curl -sS -X POST http://127.0.0.1:8099/agent/buy-wallet-bitrefill \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"<quote_id_from_quote>","recipient":{}}'

従来の /agent/buy-bitrefill ルートは、デフォルトで無効になっています。これは分離された Bankr x402 の実験専用であり、 SIGN402_ENABLE_LEGACY_PAYMENT_EXECUTOR=1 と、別途設定する SIGN402_LEGACY_OPERATOR_API_TOKEN の両方が必要です。Telegram での公開チェックアウトには /agent/buy-wallet-bitrefill を使用します。

以下のトンネルの例は、ローカルのデモを分離して実施する場合に限ります。本番ゲートウェイを公開しないでください。Hermes ウォレットプラグインでは、 VPS 上で SIGN402_GATEWAY_URL=http://127.0.0.1:8099 を設定する必要があります。

ローカルデモ用のトンネルを 1 つ公開します。

cloudflared tunnel --url http://127.0.0.1:8099

生成されたベース URL を Hermes に渡します。

SIGN402_GATEWAY_URL=https://<tunnel>.trycloudflare.com

エージェント購入プローブ

これは Hermes 用の短い UX エンドポイントです。/approve-policy でポリシーが承認された後、Hermes は 1 つのエンドポイントを呼び出せます。

curl -X POST http://127.0.0.1:8099/agent/buy-probe \
  -H "Content-Type: application/json" \
  -d '{"target":"algorand.co"}'

ゲートウェイが一連のフローを処理します。

GET resource -> 402 -> policy check -> Firefly PAYMENT approval -> Algorand payment -> X-Payment retry -> dashboard event

Hermes が受け取るのは最終的な公開結果のみで、秘密鍵を受け取ることはありません。

低レベルの支払い実行

このエンドポイントは、プロトコルのデバッグとテスト用に維持されています。メインの短縮モードのデモでは、Hermes は代わりに /agent/buy-probe を呼び出し、ゲートウェイが内部で支払いの承認と実行を行います。

低レベルのフローを手動で使用する場合は、Firefly が支払いハッシュを承認した後にのみ、これを呼び出してください。

curl -X POST http://127.0.0.1:8099/execute-payment \
  -H "Content-Type: application/json" \
  -d '{
    "policyHash": "<64 hex chars>",
    "paymentApprovalHash": "<64 hex chars>",
    "paymentRequirements": {
      "network": "algorand-testnet",
      "asset": "ALGO_TEST",
      "amountAtomic": "50000",
      "receiver": "MERCHANT_ALGO_ADDRESS",
      "resource": "/probe?target=algorand.co",
      "paymentIntent": "intent-001",
      "purpose": "x402_api_access"
    }
  }'

想定される応答：

{
  "ok": true,
  "policyHash": "...",
  "paymentApprovalHash": "...",
  "payment": {
    "txId": "...",
    "network": "algorand-testnet",
    "receiver": "...",
    "amountAtomic": "50000",
    "asset": "ALGO_TEST",
    "paymentIntent": "...",
    "policyHash": "...",
    "note": "sign402:<policyHash>:<paymentIntent>"
  }
}

最新の実行イベント

ゲートウェイは、診断用に最新の安全な実行イベントを保持します。

GET /events/latest

メインのショートモードデモでは、/agent/buy-probe がこのイベントを自動的に書き込みます。

低レベルのデバッグでは、フローの完了後にクライアントがイベントを記録できます。

curl -X POST http://127.0.0.1:8099/events/latest \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "decision": "APPROVED & EXECUTED",
      "policyHash": "<64 hex chars>",
      "paymentApprovalHash": "<64 hex chars>",
      "txId": "<algorand tx id>",
      "resource": "/probe?target=algorand.co",
      "paymentIntent": "intent-001",
      "amountAtomic": "50000",
      "asset": "ALGO_TEST",
      "network": "algorand-testnet",
      "deviceModel": 262,
      "deviceSerial": 1056,
      "remainingBudgetAtomic": "950000",
      "resourceResult": {
        "target": "algorand.co",
        "location": "Berlin",
        "httpStatus": 200,
        "latencyMs": 42,
        "result": "reachable"
      }
    }
  }'

デフォルトのイベントストアは、互換性のために従来の場所を保持します。 ダッシュボードの HTML を削除しても、既存のランタイムデータは移動も削除もされません。

<repo>/demo-dashboard/latest-run.json

MCP サーバー（リモート、Claude Code、Cursor、Codex 向け）

SingIt は、公開 Web API プロセス（sign402_gateway/web_api.py、sign402_gateway/web_mcp.py）上で、 https://app.singitai.app/mcp にリモート MCP サーバーを提供しています。これは Streamable HTTP による 最小限の MCP サーバーです。JSON レスポンスのみで、SSE ストリームもセッションもありません。1 回の POST が 1 つの回答になります。 認証方式は /v1 のほかのエンドポイントと同じです。SingIt アプリで作成した SingIt API キー（sk_singit_…）を、 Authorization: Bearer sk_singit_… として指定します（このヘッダーにしか対応していないクライアントでは x-api-key を使用します）。

ツール：

ツール	料金	内容
get_price	無料	暗号資産、金属、または FX の価格
list_price_symbols	無料	get_price が対応するすべてのシンボル
list_models	無料	SingIt API で利用できるモデル（チャット、画像、音声）と SingIt の料金
get_balance	無料、キーが必要	キーのアカウント残高：利用可能な USDC と保留中の USDC、自動チャージ
web_search	有料、search スコープが必要	Web を検索します（Exa）
read_page	有料、search スコープが必要	Web ページのテキストを読み取ります（Exa）
get_weather	有料、tools スコープが必要	GoPlausible の x402 デモによるサンプル予報（場所の指定なし）
get_singit_risk_check	有料、tools スコープが必要	固定のサンプルリクエストに対する SingIt のリスクチェック
get_x_profile	有料、tools スコープが必要	ユーザー名による X/Twitter プロフィールの取得
get_crypto_news	有料、tools スコープが必要	暗号資産市場のニュース
get_hyperliquid_market	有料、tools スコープが必要	Hyperliquid の無期限先物市場データ
get_funding_rates	有料、tools スコープが必要	複数の取引所にまたがるファンディングレート
resolve_ens	有料、tools スコープが必要	.eth 名またはアドレスを解決します
get_token_price	有料、tools スコープが必要	トークンの USD 価格

get_sign402_report（server.PAID_TOOLS 内）は MCP 経由では提供されません。デモ用の上流サービスが本番環境で 稼働していないためです。有料ツールの MCP 説明は web_mcp.PAID_TOOL_DESCRIPTIONS にあります。

有料の呼び出しはすべて /v1 と同じように課金されます。キーごとの日次上限およびリクエストごとの上限に従い、 アカウント固有の SingIt 制限の範囲内で、Base または Solana 上の USDC で課金されます。市場データツール（tools スコープ）は、 現在 Base のみに対応しています。Solana アカウントのキーは、理由が明確な拒否を受けます。ここで資金を移動したり、制限を変更したり、 商品を購入したりすることはできません（Bitrefill もウォレット／許可ツールもありません。現時点では MCP の対象外であり、早くても v2 以降です）。

tools/list のすべてのエントリには、title と MCP アノテーション（readOnlyHint、destructiveHint、 idempotentHint、openWorldHint）が付与されています。14 個のツールはすべて読み取り専用で、破壊的な操作は行いません。有料ツールはキーの 制限を消費しますが、外部の状態には一切触れません。get_price、list_price_symbols、list_models、get_balance は SingIt 独自のデータを 読み取るため、冪等であり、オープンワールドではありません。それ以外のツールは呼び出すたびに再度課金され（冪等ではありません）、サードパーティのデータにアクセスします（オープンワールド）。

インストール：

# Claude Code
claude mcp add --transport http singit https://app.singitai.app/mcp --header "Authorization: Bearer $SINGIT_KEY"

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "singit": {
      "url": "https://app.singitai.app/mcp",
      "headers": { "Authorization": "Bearer ${env:SINGIT_KEY}" }
    }
  }
}

Codex（~/.codex/config.toml）：

[mcp_servers.singit]
url = "https://app.singitai.app/mcp"
bearer_token_env_var = "SINGIT_KEY"

ローカルで試すには、ゲートウェイと Web API を起動し（SIGN402_WEB_ENABLED=1 を設定して python -m sign402_gateway.web_api を実行します。 docs/allowance-web-v1.md を参照してください）、アプリでキーを作成して、代わりに 127.0.0.1:8130 を指定します。

curl -s http://127.0.0.1:8130/mcp \
  -H "Authorization: Bearer $SINGIT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

制限：

• カタログの参照には、キーは一切不要です。initialize、ping、tools/list と3つの無料ツール（get_price、list_price_symbols、list_models）はキーなしで応答するため、MCP ディレクトリや利用者はサーバーが提供するものを確認できます。有料ツールをキーなしで呼び出すと、キーを求めるツールエラーが返されます。課金は発生しません。キーを送信するリクエストでは、有効なキーを送信する必要があります。誤ったキーや失効したキーの場合は401になり、キーなしでの処理にはフォールバックしません。
• この変更より前に作成されたキーは、answers search のみを対象として署名されており、tools スコープがありません。そのため、上記の有料データツールは、新しいキーを作成するよう求めるメッセージを返して拒否します。get_price、list_price_symbols、list_models、web_search、read_page は、それぞれのスコープに応じて、有効期限内のキーであればどれでも使用できます（web_search と read_page には search が必要です）。
• MCP には、/v1 とは別のレート制限があります。デフォルトでは、キーごと（キーがない場合はクライアントアドレスごと）に1分あたり60リクエストです（変更するには SINGIT_MCP_REQUESTS_PER_MINUTE を設定します）。そのため、一方を多用しても他方が圧迫されることはありません。ID を含むリクエスト（initialize、ping、tools/list、tools/call）ごとに1回カウントされます。通知は無料です。制限を超えると、Retry-After ヘッダー（秒数）付きの JSON-RPC エラーが返されます。web_search と read_page はここでのみ課金され、/v1 では二重に課金されません。
• 有料データツールは Base でのみ販売されています。Solana アカウントのキーでこれらのツールを呼び出すと、明確な拒否メッセージが返されます。
• ブラウザーの Origin ヘッダーを含むリクエストは、そのオリジンが信頼されていない限り拒否されます（403）。信頼されるのは、このサーバー自身のオリジン（SIGN402_WEB_URI）か、既知の MCP インスペクターおよびスキャナーの小規模な許可リスト（https://glama.ai、https://www.glama.ai、https://x402scan.com、https://www.x402scan.com）に含まれるオリジンです。カンマ区切りの SINGIT_MCP_ALLOWED_ORIGINS 環境変数で上書きできます（デフォルトへの追加ではなく、置き換えです）。信頼されたオリジンには、Origin のないリクエストと同じ応答が返されます（カタログはキーなし、有料ツールにはキーが必要です）。信頼されていないオリジンは、キーの確認前に拒否されます。OPTIONS /mcp は、同じ方法で CORS プリフライトに応答します。
• 1つのクライアントアドレスから認証の失敗（誤ったキーまたは失効したキー）が繰り返されると、10分間に30回失敗した後は401ではなく429が返され、キーの推測を抑止します。
• GET /mcp は405を返します。サーバーからクライアントへの SSE ストリームはありません。
• 各 tools/call につき、分析イベント mcp_call が1件記録されます（ツール、ステータス、エラークラス、レイテンシー、課金の有無と金額、キーのソルト付き参照、または keyless）。キー、アドレス、アカウント ID、ツール引数は記録されません。それ以外のデータも記録されません。initialize と tools/list は記録されず、分析データの書き込みに失敗しても呼び出しには影響しません。分析を参照してください。

無料のウォレット利用額レポート

Web API（app.singitai.app）の GET /v1/wallet/{address}/reconciliation（および HEAD）では、ウォレットの所有者本人に限り、SingIt 経由でそのウォレットが使用した金額と、利用枠の残額を無料で確認できます。そのアドレスでサインインするアカウントの API キー（Authorization: Bearer sk_singit_… または x-api-key）を送信してください。キーがない場合、または誤ったキーの場合は 401（api_key_required、WWW-Authenticate ヘッダー付き）、別のアカウントのキーの場合は 403（not_your_wallet）が返されます。これがなければ、誰でもあるアドレスが SingIt を使用していることや、その使用先を知ることができてしまいますが、ブロックチェーン上の情報だけではそれは分かりません。このエンドポイントは API キー用の /v1 ハンドラーより前に処理されます。省略可能なクエリパラメーター days は 1～90 で、デフォルトは 30 です。Access-Control-Allow-Origin: * を設定し、Cookie は使用しませんが、キーはサーバーコードで使用してください。Cache-Control: private, no-store が設定されています。

curl -s https://app.singitai.app/v1/wallet/0xAbC.../reconciliation?days=30 \
  -H "Authorization: Bearer $SINGIT_API_KEY"

{
  "address": "0x2222222222222222222222222222222222222222",
  "chain": "base",
  "known": true,
  "window": {"days": 30, "since": 1797408000, "until": 1800000000},
  "spent": {
    "totalAtomic": "3300000", "totalUsd": "3.30", "count": 3,
    "byCategory": {"chat_answer": {"count": 1, "atomic": "300000", "usd": "0.30"},
                   "data_tool": {"count": 1, "atomic": "1000000", "usd": "1.00"},
                   "gift_card": {"count": 1, "atomic": "2000000", "usd": "2.00"}},
    "byDay": [{"date": "2027-01-14", "atomic": "1000000", "usd": "1.00", "count": 1}]
  },
  "creditTopUps": {"count": 1, "atomic": "4000000", "usd": "4.00"},
  "allowance": {
    "configured": true, "state": "active", "dailyCapAtomic": "5000000", "perPurchaseCapAtomic": "2000000",
    "spentTodayAtomic": "300000", "remainingTodayAtomic": "4700000", "expiry": 1800864000,
    "limiter": "0x1111111111111111111111111111111111111111"
  },
  "generatedAt": 1800000000
}

• address は正規形式です。Base ではチェックサム形式、Solana では指定どおりの形式（base58 は大文字と小文字を区別します）です。chain はアドレスから判定される base または solana です。0x + 40 桁の 16 進数でも、32～44 文字の base58 でもないアドレスは 400（bad_address）になります。days が無効な場合は 400（bad_days）になります。
• 金額はすべて、USDC の最小単位（小数点以下 6 桁）を文字列で表し、それぞれに usd の文字列が添えられます。window.since と until は Unix 秒（UTC）です。byDay の日付は UTC です。
• 確定済みの利用額のみが対象です。Base では settlements の行、Solana では引き落としトランザクションがある利用額です。予約されたものの確定されなかった Solana の利用額は spent に含まれません。
• creditTopUps は、API 用に購入した残高（/v1/credit）です。別項目として報告され、spent には含まれません。
• カテゴリーは chat_answer、data_tool、gift_card（Bitrefill）、other です。Base では scripts/daily-metrics.py と同じマッピングを使用します。SingIt 自身のコードで記録されていない Solana の目的は other に分類されます。
• SingIt が一度も確認したことのないアドレスでは、allowance は null です（known: false、合計はゼロで、それ以外の形式は同じです）。Base の state は active、paused、expired、none のいずれかです。Solana では granted、waiting_for_grant、expired のいずれかで、エージェントのみが存在する場合は none です。limiter は Base のリミッターコントラクト、または Solana のデリゲートです。どちらもブロックチェーン上で公開されています。
• RPC 呼び出しは行われません。spentTodayAtomic と remainingTodayAtomic は、UTC の午前 0 時以降における当社独自の記録です。クレジットの追加購入分も、リミッター経由で支払われるため含まれます（Solana ではページのステータスと同様に、処理中の従量制回答のために確保された金額も含まれます）。Base では、ブロックチェーン上のリミッター自身が返す remainingToday() が正確な値です。Solana の granted 状態は、最後に完了した許可または取り消しの記録であり、トークンアカウントを読み取ったものではありません。
• プライバシー保護のため、カテゴリーのみを表示します。リソース URL、請求書 ID、Solana の目的テキスト、トランザクションハッシュ、チャット、メールアドレス、Telegram ID は一切表示しません。
• レート制限はクライアント IP ごとに SINGIT_RECONCILIATION_PER_MINUTE で設定します（デフォルトは 30）。制限を超えると、Retry-After: 60 とともに 429 が返されます。応答はアドレスと days ごとに、プロセス内で 60 秒間キャッシュされます。
• singit-ask の /openapi.json に掲載されています（独自の servers エントリー、支払い不要）。有料リソースのみを掲載する /.well-known/x402 には含まれません。このドキュメントには無料のエンドポイント用フィールドがありません。

GET /.well-known/mcp/server-card.json（SEP-1649 ドラフト）と GET /.well-known/glama.json は、同じホスト上で公開されているキー不要のカタログメタデータです。API キーなしで tools/list を読み取る MCP ディレクトリやスキャナー向けです。実装は web_mcp.py の server_card() と glama_json() です。

公開ブランド数値

GET https://app.singitai.app/brand/numbers.json (sign402_gateway/web_api.py) は、マーケティングサイト向けの無料・認証不要のエンドポイントです。ゲートウェイ独自の決済、利用額、アカウントの各ストアから集計した読み取り専用の件数を返します。ウォレットアドレスやアカウント ID は一切含みません。scripts/daily-metrics.py 独自のカテゴリを反映しています。決済済み件数にはクレジットのチャージは含まれません（Base は settlements.resource NOT LIKE '%/v1/credit'、Solana は spends.pull_tx IS NOT NULL）。CORS はオープン（*）で、Cache-Control: public, max-age=300 を設定しています。プロセス内で 5 分間キャッシュするため、訪問者ごとにページを更新しても、毎回 SQLite にアクセスすることはありません。また、IP ごとにレート制限されます。

例（本番の数値ではなく、tests/test_brand_numbers.py のシード済みテストデータです）：

{
  "version": 1,
  "measuredAt": "…",
  "scope": "Counts payments made through the SingIt app and its agents' Base and Solana allowance lanes (settlements and spends), excluding credit top-ups. Direct x402 calls to ask.singitai.app settle on-chain and are not counted here.",
  "chains": ["base", "solana"],
  "payments": {
    "settled": { "total": 3, "last30d": 2 },
    "payingWallets": { "total": 3, "last30d": 2 },
    "usdcVolume": { "total": 10.7, "last30d": 8.2 }
  },
  "accounts": 2,
  "mcpTools": 14,
  "models": null
}

ゲートウェイが singit-ask カタログのモデル数をすでに追跡していない限り、models は null です（この数を計算するために ask.singitai.app を取得することはありません）。ask.singitai.app への直接の x402 呼び出し（SingIt アカウントを持たず、回答ごとに支払うエージェント）はオンチェーンで決済され、含まれません。詳しくは scope を参照してください。

API キーの /v1 での無料モデル

サインイン済みのウォレットの API キーで POST /v1/chat/completions に free/<id>（例：free/deepseek-v4.1-flash）を指定すると、初回は無料で回答を取得できます。デフォルトでは無効です。SIGN402_WEB_FREE_MODELS にモデルを指定しない限り、無料にはなりません。支払いありの /v1 と同じアップストリームが必要です（SIGN402_WEB_SURPLUS_API_KEY と SIGN402_WEB_INTERNAL_TOKEN）。これらがない場合、この設定は無視され、警告がログに記録されます。モジュールは sign402_gateway/web_free.py です。

変数	意味
SIGN402_WEB_FREE_MODELS	free/<id> として無料で回答するモデル。カンマ区切りです。空または未設定（デフォルト）の場合、無効です。
SIGN402_WEB_FREE_PER_ACCOUNT_PER_DAY	アカウント（ウォレット）ごとの 1 日あたりの無料回答数。すべてのキーを合算します。デフォルトは 20 です。
SIGN402_WEB_FREE_PER_NETWORK_PER_DAY	クライアントネットワークごとの 1 日あたりの無料回答数。デフォルトは 40 です。
SIGN402_WEB_FREE_PER_DAY	全利用者合計の 1 日あたりの無料回答数。デフォルトは 1000 です。
SIGN402_WEB_FREE_MAX_TOKENS	回答の長さの上限です。デフォルトは 400 です。

正の整数でない値を指定すると、Web API は起動しません。

• 制限： アカウントごと、ネットワークごと、全利用者合計の制限のうち、いずれかに達した時点で適用されます。その後は 429 と Retry-After（UTC の午前 0 時までの秒数）が返されます。ネットワークはクライアントアドレスの IPv4 /24 または IPv6 /64 です（IPv4 にマップされた IPv6 アドレスは IPv4 /24 として扱われるため、同じサブネット内でアドレスを切り替えても割り当ては増えません）。クライアントアドレスには、Web API がすでに信頼しているアドレスを使用します。ループバックプロキシ経由の場合は Cf-Connecting-Ip または X-Forwarded-For、それ以外の場合は接続元です。
• 支払いありの制限とは別です： 無料回答はキーの 1 分あたり 60 リクエスト、1 日あたりの上限、リクエストごとの上限、残高のいずれにもカウントされず、利用額も発生しません。支払いありのリクエストはこれまでどおりカウントされます。
• 同じアップストリーム、短い回答： 質問は支払いありの /v1 と同じ Surplus アップストリームに送信されます。max_tokens は SIGN402_WEB_FREE_MAX_TOKENS 以下に制限され、質問は最大 4000 文字、ツールは使用されません。拒否された場合や回答が返ってこなかった場合は、カウントされません。
• 一覧表示： この機能が有効な場合に限り、GET /v1/models（および MCP の list_models）では、free: true と limits を持つ free/<id> エントリとして先頭に表示されます。
• MCP： MCP サーバーにはチャットツールがないため、無料回答を利用できるのは /v1 のみです。MCP のレート制限には影響しません。
• 再起動： カウンターはメモリ内にあります。再起動するとその日のカウントがリセットされるため、再起動によって 1 日分の割り当てをもう一度提供できる場合があります。ただし、1 日あたりの上限が上限となります。無料回答はこのプロセス内でのみカウントされます。
• ウォレット ID： アカウントは API キーに署名したウォレットです。そのため、制限はキーではなくウォレットに適用されます。ウォレットを増やした場合に適用される制限は、ネットワーク制限のみです。

提案、モデルごとの費用、オーナーの判断が必要な項目については docs/free-models.md を参照してください。

安全性

• ゲートウェイは、ローカルの payment-executor/.env から Algorand の秘密鍵を読み込みます。
• 秘密鍵が HTTP 経由で返されることはありません。
• Hermes が受け取るのは、支払いメタデータと txId のみです。
• Firefly の承認に失敗した場合、Hermes は /execute-payment を呼び出してはいけません。
• ダッシュボードのイベントには、安全なメタデータのみを含め、秘密鍵やニーモニックは決して含めないでください。