grid-api

Grid API スキル

Grid API を介したグローバル決済オペレーションをユーザーが行えるよう支援します。主な機能:

1. API オペレーションの実行 - curl を使用して Grid API を直接操作します
2. ドキュメントに関する質問への回答 - https://docs.lightspark.com/llms.txt または OpenAPI 仕様 (https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml) からドキュメントを取得します
3. 決済ワークフローのガイド - 銀行口座、UMA アドレス、暗号資産ウォレットへの送金をユーザーが行えるよう支援します

埋め込みウォレットのオフランプ (USDB → USD 銀行)

USDB 埋め込みウォレット → USD 銀行のオフランプフロー全体について、grid-api リポジトリに専用のドキュメントとヘルパースクリプトがあります:

• scripts/README.md — ステップバイステップの手順: オンボーディング → オンボード (on-ramp) → オフランプ (off-ramp)。コピー＆ペースト可能な curl を含み、OTP / HPKE / Turnkey スタンプの手順も解説しています。
• scripts/embedded-wallet-sign.js — @turnkey/crypto と @turnkey/api-key-stamper をラップした 3 つのサブコマンド (gen-keypair、decrypt-bundle、stamp)。初回セットアップ: cd scripts && npm install。

ユーザーが以下について質問した場合は必ず scripts/README.md を読んでください: USDB オフランプ、埋め込みウォレットの署名、payloadToSign、Grid-Wallet-Signature、Turnkey スタンプ、OTP 検証、HPKE バンドルの復号、EMAIL_OTP クレデンシャルフロー、または /auth/credentials/{id}/verify と /auth/credentials/{id}/challenge エンドポイント。

オンボーディングの落とし穴: USDB 埋め込みウォレットに対して EMAIL_OTP 認証クレデンシャルを最初の quote より前に登録してください。これがないと、クレデンシャルがトリガーされるまで Turnkey サブオーグ / Spark ネットワークウォレットがブートストラップされないため、オンボード (on-ramp) の quote が to_network INTERNAL_FUNDED_FIAT does not support USDB で失敗します。

参考資料

詳細な情報については、references/ ディレクトリにある以下のリファレンスファイルを読んでください:

• references/account-types.md - 国別の外部アカウント要件 (MXN、BRL、EUR、INR、GBP、NGN など 18 種類以上) と、フィールド要件および curl の例。国際決済用の外部アカウントを作成する際に読んでください。
• references/endpoints.md - メソッド、パス、レスポンスコードを含む完全な API エンドポイントリファレンス。特定の API 機能について質問に回答する際に読んでください。
• references/workflows.md - 一般的なシナリオ (UMA 決済、国際送金、オンボード、オフランプ) 向けのステップバイステップの決済ワークフローガイド。複数ステップの決済フローをユーザーに案内する際に読んでください。

主要な概念

エンティティ

• プラットフォーム: 最上位のエンティティ (API ユーザーのビジネス)
• 顧客: 決済を送受信するプラットフォームのエンドユーザー
• 内部アカウント: 資金を保持するための Grid 管理アカウント (プラットフォーム所有または顧客所有が可能)
• 外部アカウント: Grid 外部の銀行口座または暗号資産ウォレット (支払いの送金先)
• UMA アドレス: Universal Money Address (例: [email protected])。決済を受け取るためのアドレス

アカウントの種類

• プラットフォーム内部アカウント: プール資金、報酬分配、トレジャリー向け
• 顧客内部アカウント: 各顧客に対して自動的に作成される、通貨ごとの保有アカウント
• 外部アカウント: 従来の銀行口座 (MXN_ACCOUNT、EUR_ACCOUNT、USD_ACCOUNT など) または暗号資産ウォレット

アカウントステータスのライフサイクル

PENDING → ACTIVE → UNDER_REVIEW → INACTIVE

通貨と金額

• すべての金額は最小通貨単位で表されます (USD はセント、BTC は satoshi)
• 表示用に変換するには currency.decimals フィールドを使用します (USD=2、BTC=8 など)
• 例: decimals: 2 の場合、10000 = $100.00

設定

Grid API は HTTP Basic 認証を使用します。API 呼び出しを行う前に、認証情報とベース URL が環境変数として設定されていることを確認してください:

• GRID_CLIENT_ID - API クライアント ID
• GRID_CLIENT_SECRET - API クライアントシークレット
• GRID_BASE_URL - API ベース URL

設定されていない場合は、~/.grid-credentials から読み込んでください:

export GRID_CLIENT_ID=$(jq -r '.clientId // .apiTokenId' ~/.grid-credentials)
export GRID_CLIENT_SECRET=$(jq -r '.clientSecret // .apiClientSecret' ~/.grid-credentials)
export GRID_BASE_URL=$(jq -r '.baseUrl // "https://api.lightspark.com/grid/2025-10-13"' ~/.grid-credentials)

環境変数がまだ設定されていない場合は、API 呼び出しを行う前に必ず ~/.grid-credentials から認証情報を読み込んでください。

ベース URL

• 本番環境: https://api.lightspark.com/grid/2025-10-13
• 開発環境またはローカル: 異なるベース URL を使用する場合があります — ~/.grid-credentials の baseUrl フィールドを確認してください

ドキュメントリソース

このスキルの参照ファイルでカバーされていない質問については、Web から追加情報を取得してください:

• LLM 最適化ドキュメント: Grid API の簡潔な概要については https://docs.lightspark.com/llms.txt を、包括的なドキュメントについては https://docs.lightspark.com/llms-full.txt を取得してください
• OpenAPI 仕様: リクエスト/レスポンス定義を含む完全な API スキーマについては https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml を取得してください
• 公開ドキュメント: ガイド、チュートリアル、API リファレンスについては https://docs.lightspark.com を参照してください。どのページも .md サフィックスを使用することで、エージェントがより読みやすい形式になります。

API 呼び出しの実行

すべての API 呼び出しは curl -u を介した HTTP Basic 認証を使用します:

curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/<endpoint>"

POST/PATCH リクエストの場合は、JSON ボディを追加してください:

curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '<json-body>' \
  "$GRID_BASE_URL/<endpoint>"

読みやすい出力にするには jq を通してください: | jq .

API オペレーション

プラットフォーム設定

# Get platform config (currencies, limits)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/config" | jq .

# Update platform config (e.g., set webhook endpoint)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X PATCH -H "Content-Type: application/json" \
  -d '{"webhookEndpoint": "https://example.com/webhooks"}' \
  "$GRID_BASE_URL/config" | jq .

顧客管理

# List customers
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/customers?limit=20" | jq .

# Get customer details
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/customers/<customerId>" | jq .

# Create customer (INDIVIDUAL)
# Optional individual fields: region, currencies, email, phoneNumber, nationality, address,
# birthDate, and idType/identifier (US SSN/ITIN — write-only, never returned).
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "<platform-id>",
    "customerType": "INDIVIDUAL",
    "fullName": "Name"
  }' \
  "$GRID_BASE_URL/customers" | jq .

# Create customer (BUSINESS)
# businessInfo REQUIRES legalName, taxId, and incorporatedOn (ISO date YYYY-MM-DD).
# Always send businessType too: it's optional to the schema, but receivers can
# require it, and without it POST /quotes fails with MISSING_MANDATORY_USER_INFO.
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "<platform-id>",
    "customerType": "BUSINESS",
    "businessInfo": {
      "legalName": "Acme Corporation, Inc.",
      "taxId": "47-1234567",
      "incorporatedOn": "2018-03-14",
      "businessType": "INFORMATION"
    }
  }' \
  "$GRID_BASE_URL/customers" | jq .

# Update customer (customerType is required)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X PATCH -H "Content-Type: application/json" \
  -d '{"customerType": "INDIVIDUAL", "fullName": "New Name"}' \
  "$GRID_BASE_URL/customers/<customerId>" | jq .

# Delete customer
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X DELETE \
  "$GRID_BASE_URL/customers/<customerId>" | jq .

# Generate KYC link (POST; Grid customerId in the path, redirectUri in the JSON body)
# Returns kycUrl (hosted flow) plus an optional token (for embedding the provider SDK).
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{"redirectUri": "https://example.com/callback"}' \
  "$GRID_BASE_URL/customers/<customerId>/kyc-link" | jq .

アカウント管理

# List customer internal accounts
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/customers/internal-accounts?customerId=<customerId>" | jq .

# List platform internal accounts
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/platform/internal-accounts" | jq .

# List customer external accounts
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/customers/external-accounts?customerId=<customerId>" | jq .

# Create external account (example: Mexico MXN_ACCOUNT - Individual)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customerId>",
    "currency": "MXN",
    "accountInfo": {
      "accountType": "MXN_ACCOUNT",
      "clabeNumber": "<18-digit-number>",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Full Name",
        "birthDate": "1990-01-15",
        "nationality": "MX"
      }
    }
  }' \
  "$GRID_BASE_URL/customers/external-accounts" | jq .

サポートされている 27 種類のフィアットアカウントタイプと 7 種類の暗号資産ウォレットタイプ、およびそれぞれのフィールド要件については、references/account-types.md をお読みください。

為替レート（見積もり前の FX レート）

受取アカウントや見積もりを作成する前に、送金コリドーの参考 FX レートを確認するために使用します。レートは約 5 分間キャッシュされ、プラットフォーム固有の手数料が含まれます。

# Get all available corridors from USD
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/exchange-rates?sourceCurrency=USD" | jq .

# Get rate for a specific corridor (USD → INR)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/exchange-rates?sourceCurrency=USD&destinationCurrency=INR" | jq .

# Get rate with a specific sending amount (10000 = $100.00 in cents)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/exchange-rates?sourceCurrency=USD&destinationCurrency=INR&sendingAmount=10000" | jq .

# Get rates for multiple destination currencies
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/exchange-rates?sourceCurrency=USD&destinationCurrency=INR&destinationCurrency=EUR" | jq .

レスポンスにはコリドーごとに以下が含まれます:

• sourceCurrency / destinationCurrency — コード、小数点以下桁数、名前、シンボル付き
• destinationPaymentRail（例: UPI、SEPA_INSTANT、MOBILE_MONEY、FASTER_PAYMENTS）
• sendingAmount / receivingAmount — 最小通貨単位
• minSendingAmount / maxSendingAmount — コリドーの上限・下限
• exchangeRate — 送金通貨 1 単位あたりの受取通貨単位
• fees.fixed — 送金通貨の最小単位での固定手数料
• updatedAt — レートが最後に更新された日時

注意: これらは参考用のキャッシュされたレートです。ロックされた実行可能なレートが必要な場合は、POST /quotes で見積もりを作成してください。

暗号資産出金手数料の見積もり

暗号資産の出金前にネットワーク手数料とアプリケーション手数料を見積もります:

curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "internalAccountId": "<internalAccountId>",
    "currency": "USDC",
    "cryptoNetwork": "SOLANA",
    "amount": 1000000,
    "destinationAddress": "<blockchain-address>"
  }' \
  "$GRID_BASE_URL/crypto/estimate-withdrawal-fee" | jq .

戻り値:

• networkFee — networkFeeAsset 単位でのガス手数料（例: SOL の場合は lamports）
• networkFeeAsset — ネットワーク手数料に使用される資産（例: SOL）
• applicationFee — 出金通貨単位でのプラットフォーム手数料
• totalFee — 出金通貨での合計コスト（換算されたネットワーク手数料 + アプリケーション手数料）
• netAmount — すべての手数料を差し引いた後に受取人が受け取る金額

サポートされているネットワーク: SOLANA、ETHEREUM、BASE、POLYGON、ARBITRUM、SPARK、LIGHTNING、BITCOIN

見積もり（クロスカレンシー送金）

# Account-funded to UMA: Use when funds are already in an internal account
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "<internalAccountId>"
    },
    "destination": {
      "destinationType": "UMA_ADDRESS",
      "umaAddress": "<address>",
      "currency": "USD"
    },
    "lockedCurrencyAmount": 10000,
    "lockedCurrencySide": "SENDING"
  }' \
  "$GRID_BASE_URL/quotes" | jq .

# Account-funded to external account: currency is intrinsic to the account, so it is NOT
# sent in the destination. The only optional field on an ACCOUNT destination is paymentRail.
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "<internalAccountId>"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "<externalAccountId>"
    },
    "lockedCurrencyAmount": 10000,
    "lockedCurrencySide": "SENDING"
  }' \
  "$GRID_BASE_URL/quotes" | jq .

# Real-time/JIT funded: Returns paymentInstructions for funding.
# When the funding currency is a stablecoin (USDC/USDT), the source MUST include cryptoNetwork.
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "source": {
      "sourceType": "REALTIME_FUNDING",
      "customerId": "<customerId>",
      "currency": "USDC",
      "cryptoNetwork": "SOLANA"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "<accountId>"
    },
    "lockedCurrencyAmount": 100000,
    "lockedCurrencySide": "RECEIVING"
  }' \
  "$GRID_BASE_URL/quotes" | jq .

# Execute a quote
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST \
  "$GRID_BASE_URL/quotes/<quoteId>/execute" | jq .

# List quotes
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/quotes?status=PENDING" | jq .

# Get quote details
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/quotes/<quoteId>" | jq .

見積もりの任意のトップレベルフィールド（source / destination の兄弟であり、senderCustomerInfo の中にネストされません）:

• purposeOfPayment — 支払いが行われる理由を表す列挙型 （GOODS_OR_SERVICES、GIFT、SELF、SALARY_PAYMENT、FAMILY_SUPPORT、OTHER など）。 一部のコリドー（例: インド）では必須です。
• remittanceInformation — 送金レール上で支払いとともに運ばれる自由形式のメモ（最大 80 文字） （ACH アデンダ、FedNow/RTP 送金フィールド、電信送金 OBI）。

宛先の currency: UMA_ADDRESS 宛先の場合にのみ指定してください。ACCOUNT 宛先の場合、通貨はアカウントに固有であり省略する必要があります。唯一の任意 フィールドは paymentRail です。

強力な顧客認証（SCA）

SCA 規制対象地域（例: EU）のお客様は、資金が移動する前にチャレンジで送金を承認する必要があります。非 SCA のお客様にはこれらは一切表示されません。チャレンジをトリガーするエントリポイントは 2 つあります:

• プリファンド済みクォートの実行 — POST /quotes/{quoteId}/execute は、送金を開始する代わりに、クォートを PENDING_AUTHORIZATION と scaChallenge 付きで返します。すでに保持しているクォートを承認することで解放します。execute を再度呼び出すと 409 が返ります。
• リアルタイムファンディングクォートの作成 — POST /quotes は 202 を返し、クォートが PENDING_AUTHORIZATION になることがあります。この場合、チャレンジが承認されるまで paymentInstructions は保留されます。

チャレンジを承認します（サンドボックスの SMS コードは常に 123456 です）:

curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{"code": "123456"}' \
  "$GRID_BASE_URL/quotes/<quoteId>/authorize" | jq .

更新されたクォートが返されます。それでも PENDING_AUTHORIZATION の場合、次の scaChallenge が含まれています。進展するまで再度承認してください（リアルタイムファンディングクォートでは paymentInstructions が設定されます）。

期限切れの SMS コードを再送します（同じチャレンジを再利用します。PASSKEY チャレンジは再送できません）:

curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST \
  "$GRID_BASE_URL/quotes/<quoteId>/authorize/resend"

オプションで、クォート作成時または実行時に scaFactor で優先チャレンジファクターをリクエストできます。値は SMS_OTP（デフォルト）または PASSKEY です。

同一通貨送金

/quotes を "immediatelyExecute": true で使用します。/transfer-in と /transfer-out エンドポイントは非推奨です。

# External → internal, same currency (source must support pull, e.g. ACH pull)
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "source": {"sourceType": "ACCOUNT", "accountId": "<externalAccountId>"},
    "destination": {"destinationType": "ACCOUNT", "accountId": "<internalAccountId>"},
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "immediatelyExecute": true
  }' \
  "$GRID_BASE_URL/quotes" | jq .

# Internal → external, same currency
# Optional: top-level "remittanceInformation" (memo, max 80 chars) and a "paymentRail"
# inside the destination to pick a specific supported rail.
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "source": {"sourceType": "ACCOUNT", "accountId": "<internalAccountId>"},
    "destination": {"destinationType": "ACCOUNT", "accountId": "<externalAccountId>", "paymentRail": "<rail>"},
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "immediatelyExecute": true,
    "remittanceInformation": "Invoice 1234"
  }' \
  "$GRID_BASE_URL/quotes" | jq .

トランザクション

# List transactions
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/transactions?status=PENDING" | jq .

# Get transaction details
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/transactions/<transactionId>" | jq .

# Approve incoming payment
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST \
  "$GRID_BASE_URL/transactions/<transactionId>/approve" | jq .

# Reject incoming payment
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{"reason": "Reason for rejection"}' \
  "$GRID_BASE_URL/transactions/<transactionId>/reject" | jq .

受取人の検索

# Look up UMA address capabilities
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/receiver/uma/%24alice%40example.com" | jq .

# Look up external account capabilities
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  "$GRID_BASE_URL/receiver/external-account/<accountId>" | jq .

注意: UMA アドレスには $ が含まれており、パス内で %24 として URL エンコードする必要があります。

サンドボックステスト

# Fund an internal account in sandbox
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{"amount": 100000}' \
  "$GRID_BASE_URL/sandbox/internal-accounts/<internalAccountId>/fund" | jq .

# Simulate sending funds to a real-time quote
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{"quoteId": "<quoteId>", "currencyCode": "<code>"}' \
  "$GRID_BASE_URL/sandbox/send" | jq .

# Simulate receiving a UMA payment
curl -s -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "senderUmaAddress": "[email protected]",
    "receiverUmaAddress": "<receiverAddress>",
    "receivingCurrencyCode": "USD",
    "receivingCurrencyAmount": 1000
  }' \
  "$GRID_BASE_URL/sandbox/uma/receive" | jq .

支払いフローパターン

Grid は 3 つの主要な支払いパターンをサポートしています:

1. プリファンド（アカウントファンディング）

資金はすでに内部アカウントにあります。クォートは既存の残高から即座に実行されます。

Internal Account (USD) → Quote → External Account/UMA (EUR)

内部アカウント ID とともに sourceType: "ACCOUNT" を使用します。

2. ジャストインタイム（リアルタイムファンディング）

資金は実行時に提供されます。クォートは複数のファンディングオプションを含む paymentInstructions を返します。入金が受信されると Grid が自動実行します。

Customer sends crypto/fiat → Grid detects deposit → Auto-executes at locked rate

顧客 ID と通貨とともに sourceType: "REALTIME_FUNDING" を使用します。インスタント決済方法でのみ動作します。

3. 同一通貨送金

通貨換算を行わずにアカウント間で送金します。これらは他の送金と同様に /quotes を経由します。immediatelyExecute を設定すると、1 回の呼び出しで作成と実行を行います。

External Account (USD) → Internal Account (USD)
Internal Account (USD) → External Account (USD)

インタラクティブな支払いワークフロー

ステップバイステップの支払いワークフローについては、references/workflows.md をお読みください。一般的なワークフロー:

• FX レートの確認（クォート前）: アカウントやクォートを設定する前に、参考レートを GET /exchange-rates で照会します
• UMA 支払い: 受取人の検索 -> クォート -> 確認 -> 実行
• 国際銀行送金: 外部アカウントの作成 -> 受取人の検索 -> クォート -> 確認 -> 実行
• オンランプ（フィアットから暗号資産）: KYC の確認 -> フィアットの入金 -> 暗号資産外部アカウントの作成 -> immediatelyExecute 付きのクォート
• オフランプ（暗号資産からフィアット）: フィアット外部アカウントの作成 -> 暗号資産の入金 -> クォート -> 実行
• 受信支払いの処理: 保留中の承認の一覧表示 -> レビュー -> 承認/拒否

リアルタイム / ジャストインタイム資金調達型送金

ユーザーが「リアルタイム見積もり」または「ジャストインタイム」資金調達型送金を求めた場合は、このフローを使用してください。即時決済手段でのみ使用してください。見積もりはすぐに失効するため、ACH のような低速な手段では使用しないでください。

互換性のある即時手段:

• 暗号資産: BTC (Lightning、Spark)、USDC (Solana、Base、Polygon、Ethereum、Arbitrum)、USDT (Tron、Ethereum、Plasma、Arbitrum)
• 法定通貨: RTP、SEPA Instant、その他の即時決済レール

フロー:

1. sourceType: "REALTIME_FUNDING" で見積もりを作成します。宛先には内部アカウント、外部アカウント、または UMA アドレスを指定できます。
2. レスポンスには 複数の資金調達オプションを同時に 含む paymentInstructions が含まれます (例: BTC なら Lightning + Spark、USDC なら Solana + Base + Polygon)。すべてのオプションをユーザーに表示してください。
3. 自動実行: ユーザーが提供されたいずれかのアドレスに資金を送金すると、Grid が入金を自動的に検出し、ロックされたレートで実行します。JIT 見積もりのために execute エンドポイントを呼び出さないでください。送信される Webhook: 入金時に internal-account-status、完了時に outgoing-payment。
4. 見積もりの失効: 見積もりは 1〜5 分で失効します。失効した場合は、新しい見積もりを作成してください。

ベストプラクティスとよくある落とし穴

1. まずプラットフォーム設定を確認する: GET /config を呼び出して、サポートされている通貨と必須フィールドを確認します
2. 最小通貨単位を使用する: すべての金額はセント/サトシ単位です。表示には decimals フィールドを使用してください
3. 見積もりの失効を処理する: 見積もりは 1〜5 分で失効します。新しい見積もりを作成できるように準備してください
4. 適切なフローを選択する: 即時実行にはプリファンディング、暗号資産/即時レールには JIT を使用してください
5. jq にパイプする: 読みやすい出力のために常に | jq . を追加するか、特定の値を抽出するには | jq -r .field を使用してください
6. 特殊文字を URL エンコードする: UMA アドレスには $ が含まれます。URL パスでは %24 としてエンコードしてください
7. 宛先通貨は UMA 専用です: 宛先オブジェクトの currency は UMA_ADDRESS 宛先の場合にのみ指定してください。ACCOUNT 宛先の場合、通貨はアカウントに固有であり、省略する必要があります。そこでの唯一のオプションフィールドは paymentRail です
8. 個人受益者には fullName が必要です: beneficiaryType: "INDIVIDUAL" の場合、fullName は必須です。birthDate (YYYY-MM-DD) と nationality (2 文字コード) はオプションですが推奨されます
9. 正しいナイジェリアのフィールド名を使用する: bankName (bankCode ではない) を使用し、purposeOfPayment を含めてください
10. 国固有の必須フィールドを忘れないでください: ブラジル (BRL_ACCOUNT) には pixKey、pixKeyType、taxId が必要です。ヨーロッパ (EUR_ACCOUNT) には iban が必要です。すべての法定通貨アカウントには beneficiary が必要です。paymentRails を送信しないでください。Grid がレールを選択し、作成されたアカウントでそれを返します。

エラー処理

単一リソースのレスポンス:

{
  "id": "...",
  "status": "...",
  ...
}

リストレスポンスは、ページネーションフィールドを含む data 配列に結果を返します:

{
  "data": [ ... ],
  "hasMore": true,
  "nextCursor": "...",
  "totalCount": 42
}

結果を反復するには jq '.data[]' を、フィルタリングするには jq '[.data[] | select(.currency == "NGN")]' を使用してください。

エラーの場合:

{
  "code": "ERROR_CODE",
  "message": "Human readable message"
}

HTTP ステータスコードはエラーカテゴリを示します (400 は不正な入力、401 は認証の問題、404 は見つからない場合など)。

よくあるエラーコード

見積もり/送金エラー:

• QUOTE_EXPIRED - 見積もりがタイムアウトしました。新しい見積もりを作成してください
• INSUFFICIENT_BALANCE - 送金前に内部アカウントの残高を確認してください
• INVALID_BANK_ACCOUNT - 各国の要件に従ってフィールド形式を検証してください
• QUOTE_EXECUTION_FAILED - 一時的なエラーです。指数バックオフで再試行してください

受信支払いエラー:

• PAYMENT_APPROVAL_TIMED_OUT - 5 秒以内に Webhook 承認を受信しませんでした
• PAYMENT_APPROVAL_WEBHOOK_ERROR - Webhook がエラーを返しました

検証エラー:

• INVALID_INPUT - 必須フィールドを確認してください。reason フィールドに詳細があります
• MISSING_MANDATORY_USER_INFO - 顧客または送信者の情報に必須フィールドが欠けています

常に HTTP ステータスコードを確認し、エラーをユーザーに明確に報告してください。