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 — 分步指南：开户 → 入金 → 提现，附带可直接复制粘贴的 curl 命令，包括 OTP / HPKE / Turnkey 签章流程。
• scripts/embedded-wallet-sign.js — 包含三个子命令（gen-keypair、decrypt-bundle、stamp），封装了 @turnkey/crypto 和 @turnkey/api-key-stamper。一次性设置：cd scripts && npm install。

用户询问以下内容时，请阅读 scripts/README.md：USDB 提现、嵌入式钱包签名、payloadToSign、Grid-Wallet-Signature、Turnkey 签章、OTP 验证、HPKE bundle 解密、EMAIL_OTP 凭证流程，或 /auth/credentials/{id}/verify 和 /auth/credentials/{id}/challenge 端点。

开户注意事项：必须在首次获取报价前，为 USDB 嵌入式钱包注册 EMAIL_OTP 身份验证凭证。否则，入金报价会因 to_network INTERNAL_FUNDED_FIAT does not support USDB 而失败，因为只有在凭证触发后，Turnkey 子组织 / Spark 网络钱包才会完成初始化。

参考资料

如需详细信息，请阅读 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 地址：用于收款的通用货币地址（例如 [email protected]）

账户类型

• 平台内部账户：用于汇集资金、发放奖励和资金管理
• 客户内部账户：为每位客户自动创建的各币种存放账户
• 外部账户：传统银行账户（MXN_ACCOUNT、EUR_ACCOUNT、USD_ACCOUNT 等）或加密货币钱包

账户状态生命周期

PENDING → ACTIVE → UNDER_REVIEW → INACTIVE

货币和金额

• 所有金额均以货币最小单位表示（USD 为美分，BTC 为聪）
• 使用 currency.decimals 字段转换显示金额（USD=2，BTC=8 等）
• 示例：10000 且 decimals: 2 = $100.00

配置

Grid API 使用 HTTP Basic Auth。发起任何 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 加载凭据。

Base URL

• 生产环境：https://api.lightspark.com/grid/2025-10-13
• 开发或本地环境：可能使用不同的 Base URL — 请查看 ~/.grid-credentials 中的 baseUrl 字段

文档资源

对于本技能参考文件未涵盖的问题，请从网上获取更多信息：

• 针对大模型优化的文档：获取 https://docs.lightspark.com/llms.txt，了解 Grid API 的简要概览；或获取 https://docs.lightspark.com/llms-full.txt，查看完整文档
• OpenAPI 规范：获取 https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml，查看包含请求/响应定义的完整 API 架构
• 已发布的文档：访问 https://docs.lightspark.com，查看指南、教程和 API 参考。任何页面都可以使用 .md 后缀，以获取更便于 Agent 阅读的格式。

发起 API 调用

所有 API 调用均通过 curl -u 使用 HTTP Basic Auth：

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。

汇率（报价前外汇汇率）

在创建收款账户或报价之前，使用此功能查看支付路径的指示性外汇汇率。汇率缓存约 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 — 每单位源货币可兑换的目标货币单位数
• 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 单位表示的 Gas 费用（例如 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 addenda、FedNow/RTP 汇款字段、wire OBI）。

目标 currency：仅当目标类型为 UMA_ADDRESS 时才指定。对于 ACCOUNT 目标，货币由账户本身决定，必须省略；唯一的可选字段是 paymentRail。

强客户认证（SCA）

位于受 SCA 监管地区（例如欧盟）的客户必须先通过验证挑战授权转账，资金才会转移。不受 SCA 约束的客户不会看到这些内容。以下两个入口会触发验证挑战：

• 执行预注资报价 — POST /quotes/{quoteId}/execute 会返回状态为 PENDING_AUTHORIZATION 且带有 scaChallenge 的报价，而不会发起转账。通过授权你已持有的报价来放行；再次调用 execute 会返回 409。
• 创建实时注资报价 — POST /quotes 可能会返回状态码 202，并返回状态为 PENDING_AUTHORIZATION 的报价；在验证挑战通过授权之前，不会提供 paymentInstructions。

授权验证挑战（沙盒短信验证码始终为 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）。

重新发送已过期的短信验证码（复用同一验证挑战；无法重新发送 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 地址中包含 $，在路径中必须将其 URL 编码为 %24。

沙盒测试

# 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 支持三种主要支付模式：

1. 预注资（账户注资）

资金已存入内部账户。报价会立即从现有余额中执行。

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

使用 sourceType: "ACCOUNT" 并提供内部账户 ID。

2. 即时注资（实时注资）

资金将在执行时提供。报价会返回包含多个注资选项的 paymentInstructions。收到存款后，Grid 会自动执行。

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

使用 sourceType: "REALTIME_FUNDING" 并提供客户 ID 和币种。仅适用于即时结算方式。

3. 同币种转账

账户之间无需货币兑换的转账。这类转账与其他转账一样通过 /quotes 进行；将 immediatelyExecute 设为 true，即可在一次调用中创建并执行。

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

交互式支付工作流

如需了解分步支付工作流，请阅读 references/workflows.md。常见工作流：

• 查询汇率（报价前）：在设置账户或报价之前，查询 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 报价，切勿调用执行端点。发送的 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：仅对 UMA_ADDRESS 目的地在目的地对象中指定 currency。对于 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 状态码，并向用户清楚说明错误。