Grid API Skill

Assist users with global payment operations via the Grid API. Core capabilities:

Execute API Operations - Use
```
curl
```
to interact with the Grid API directly
Answer Documentation Questions - Fetch docs from https://grid.lightspark.com/llms.txt or the OpenAPI spec (https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml)
Guide Payment Workflows - Help users send payments to bank accounts, UMA addresses, and crypto wallets

通过Grid API协助用户进行全球支付操作。核心功能：

执行API操作 - 使用
```
curl
```
直接与Grid API交互
解答文档相关问题 - 从https://grid.lightspark.com/llms.txt或OpenAPI规范（https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml）获取文档内容
指导支付工作流 - 帮助用户向银行账户、UMA地址和加密货币钱包发起支付

Supporting References

参考资料

For detailed information, read these reference files in the

references/

directory:

references/account-types.md
- Country-specific external account requirements (CLABE, PIX, IBAN, UPI, etc.) with field requirements and curl examples. Read this when creating external accounts for international payments.
references/endpoints.md
- Complete API endpoint reference with methods, paths, and response codes. Read this when answering questions about specific API capabilities.
references/workflows.md
- Step-by-step payment workflow guides for common scenarios (UMA payments, international transfers, on-ramp, off-ramp). Read this when guiding users through multi-step payment flows.

如需详细信息，请阅读

references/

目录下的以下参考文件：

references/account-types.md
- 特定国家的外部账户要求（CLABE、PIX、IBAN、UPI等），包含字段要求和curl示例。创建国际支付的外部账户时请阅读此文件。
references/endpoints.md
- 完整的API端点参考，包含请求方法、路径和响应代码。解答特定API功能相关问题时请阅读此文件。
references/workflows.md
- 常见场景的分步支付工作流指南（UMA支付、国际转账、法币入金、法币出金）。指导用户完成多步骤支付流程时请阅读此文件。

Key Concepts

核心概念

Entities

实体

Platform: The top-level entity (the API user's business)
Customer: End users of the platform who send/receive payments
Internal Account: Grid-managed account for holding funds (can be platform-owned or customer-owned)
External Account: Bank account or crypto wallet outside Grid (destination for payouts)
UMA Address: Universal Money Address (e.g.,
```
$user@domain.com
```
) for receiving payments

Platform（平台）：顶级实体（API用户的业务主体）
Customer（客户）：平台的终端用户，可发起/接收支付
Internal Account（内部账户）：由Grid管理的资金账户（可归平台或客户所有）
External Account（外部账户）：Grid体系外的银行账户或加密货币钱包（付款的目标账户）
UMA Address（UMA地址）：用于接收支付的通用资金地址（例如：
```
$user@domain.com
```
）

Account Types

账户类型

Platform internal accounts: For pooled funds, rewards distribution, treasury
Customer internal accounts: Per-currency holding accounts created automatically for each customer
External accounts: Traditional bank accounts (CLABE, IBAN, UPI, etc.) or crypto wallets

平台内部账户：用于资金池、奖励发放、财务资金管理
客户内部账户：为每个客户自动创建的多币种资金账户
外部账户：传统银行账户（CLABE、IBAN、UPI等）或加密货币钱包

Account Status Lifecycle

账户状态生命周期

PENDING

→

ACTIVE

→

UNDER_REVIEW

→

INACTIVE

PENDING

→

ACTIVE

→

UNDER_REVIEW

→

INACTIVE

Currency & Amounts

货币与金额

All amounts are in the smallest currency unit (cents for USD, satoshis for BTC)
Use the
```
currency.decimals
```
field to convert for display (USD=2, BTC=8, etc.)
Example:
```
10000
```
with
```
decimals: 2
```
= $100.00

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

Configuration

配置

The Grid API uses HTTP Basic Auth. Before making any API calls, ensure credentials and base URL are set as environment variables:

```
GRID_API_TOKEN_ID
```
- API token ID
```
GRID_API_CLIENT_SECRET
```
- API client secret
```
GRID_BASE_URL
```
- API base URL

If not set, load them from

~/.grid-credentials

:

bash

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

Always load credentials from
~/.grid-credentials
before making API calls if the environment variables are not already set.

Grid API使用HTTP Basic Auth。发起任何API调用前，请确保凭证和基础URL已设置为环境变量：

```
GRID_API_TOKEN_ID
```
- API令牌ID
```
GRID_API_CLIENT_SECRET
```
- API客户端密钥
```
GRID_BASE_URL
```
- API基础URL

如果未设置，请从

~/.grid-credentials

加载：

bash

export GRID_API_TOKEN_ID=$(jq -r .apiTokenId ~/.grid-credentials)
export GRID_API_CLIENT_SECRET=$(jq -r .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

基础URL

Production:

https://api.lightspark.com/grid/2025-10-13

Dev or local: May use a different base URL — check
```
~/.grid-credentials
```
for the
```
baseUrl
```
field

生产环境：

https://api.lightspark.com/grid/2025-10-13

开发或本地环境：可能使用不同的基础URL — 请查看
```
~/.grid-credentials
```
中的
```
baseUrl
```
字段

Documentation Resources

文档资源

For questions not covered by this skill's reference files, fetch additional information from the web:

LLM-optimized docs: Fetch
```
https://grid.lightspark.com/llms.txt
```
for a concise overview of the Grid API, or
```
https://grid.lightspark.com/llms-full.txt
```
for comprehensive documentation

OpenAPI Spec: Fetch

https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml

for the full API schema with request/response definitions

Published docs: Browse
```
https://grid.lightspark.com
```
for guides, tutorials, and API reference. Any page can use the
```
.md
```
suffix for a more agent-readable format.

对于本Skill参考文件未覆盖的问题，可从网络获取更多信息：

LLM优化文档：获取
```
https://grid.lightspark.com/llms.txt
```
以获取Grid API的简明概述，或
```
https://grid.lightspark.com/llms-full.txt
```
获取完整文档

OpenAPI规范：获取

https://raw.githubusercontent.com/lightsparkdev/grid-api/refs/heads/main/openapi.yaml

以获取包含请求/响应定义的完整API架构

官方发布文档：浏览
```
https://grid.lightspark.com
```
获取指南、教程和API参考。所有页面均可使用
```
.md
```
后缀以获得更适合Agent读取的格式。

Making API Calls

发起API调用

All API calls use HTTP Basic Auth via

curl -u

:

bash

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET" \
  "$GRID_BASE_URL/<endpoint>"

For POST/PATCH requests, add the JSON body:

bash

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

Pipe through

jq

for readable output:

| jq .

所有API调用均通过

curl -u

使用HTTP Basic Auth：

bash

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET" \
  "$GRID_BASE_URL/<endpoint>"

对于POST/PATCH请求，需添加JSON请求体：

bash

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

通过

jq

管道输出以获得可读格式：

| jq .

API Operations

API操作

Platform Configuration

平台配置

bash

undefined

bash

undefined

Get platform config (currencies, limits)

获取平台配置（支持的货币、限额）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/config" | jq .

Update platform config (e.g., set webhook endpoint)

更新平台配置（例如：设置webhook端点）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X PATCH -H "Content-Type: application/json"
-d '{"webhookEndpoint": "https://example.com/webhooks"}'
"$GRID_BASE_URL/config" | jq .

undefined

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X PATCH -H "Content-Type: application/json"
-d '{"webhookEndpoint": "https://example.com/webhooks"}'
"$GRID_BASE_URL/config" | jq .

undefined

Customer Management

客户管理

bash

undefined

bash

undefined

List customers

列出客户

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/customers?limit=20" | jq .

Get customer details

获取客户详情

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/customers/<customerId>" | jq .

Create customer

创建客户

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "platformCustomerId": "<platform-id>", "customerType": "INDIVIDUAL", "fullName": "Name" }'
"$GRID_BASE_URL/customers" | jq .

Update customer (customerType is required)

更新客户（customerType为必填项）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_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_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X DELETE
"$GRID_BASE_URL/customers/<customerId>" | jq .

Generate KYC link (GET with query params)

生成KYC链接（带查询参数的GET请求）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/customers/kyc-link?platformCustomerId=<platformCustomerId>&redirectUri=https://example.com/callback" | jq .

undefined

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/customers/kyc-link?platformCustomerId=<platformCustomerId>&redirectUri=https://example.com/callback" | jq .

undefined

Account Management

账户管理

bash

undefined

bash

undefined

List customer internal accounts

列出客户内部账户

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/customers/internal-accounts?customerId=<customerId>" | jq .

List platform internal accounts

列出平台内部账户

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/platform/internal-accounts" | jq .

List customer external accounts

列出客户外部账户

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/customers/external-accounts?customerId=<customerId>" | jq .

Create external account (example: Mexico CLABE - Individual)

创建外部账户（示例：墨西哥CLABE - 个人账户）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "customerId": "<customerId>", "currency": "MXN", "accountInfo": { "accountType": "CLABE", "clabeNumber": "<18-digit-number>", "beneficiary": { "beneficiaryType": "INDIVIDUAL", "fullName": "Full Name", "birthDate": "1990-01-15", "nationality": "MX" } } }'
"$GRID_BASE_URL/customers/external-accounts" | jq .


For all supported account types (PIX, IBAN, UPI, NGN, US, crypto wallets) and their field requirements, read `references/account-types.md`.

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "customerId": "<customerId>", "currency": "MXN", "accountInfo": { "accountType": "CLABE", "clabeNumber": "<18-digit-number>", "beneficiary": { "beneficiaryType": "INDIVIDUAL", "fullName": "Full Name", "birthDate": "1990-01-15", "nationality": "MX" } } }'
"$GRID_BASE_URL/customers/external-accounts" | jq .


如需了解所有支持的账户类型（PIX、IBAN、UPI、NGN、美国账户、加密货币钱包）及其字段要求，请阅读`references/account-types.md`。

Quotes (Cross-Currency Transfers)

报价（跨币种转账）

bash

undefined

bash

undefined

Account-funded to UMA: Use when funds are already in an internal account

账户资金支付至UMA：适用于资金已在内部账户的场景

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_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: IMPORTANT - always include destination currency

账户资金支付至外部账户：重要提示 - 必须包含目标货币

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "source": { "sourceType": "ACCOUNT", "accountId": "<internalAccountId>" }, "destination": { "destinationType": "ACCOUNT", "accountId": "<externalAccountId>", "currency": "<currency>" }, "lockedCurrencyAmount": 10000, "lockedCurrencySide": "SENDING" }'
"$GRID_BASE_URL/quotes" | jq .

Real-time/JIT funded: Returns paymentInstructions for funding

实时/JIT资金支付：返回包含资金选项的paymentInstructions

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "source": { "sourceType": "REALTIME_FUNDING", "customerId": "<customerId>", "currency": "<sourceCurrency>" }, "destination": { "destinationType": "ACCOUNT", "accountId": "<accountId>", "currency": "<destCurrency>" }, "lockedCurrencyAmount": 100000, "lockedCurrencySide": "RECEIVING" }'
"$GRID_BASE_URL/quotes" | jq .

Execute a quote

执行报价

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST
"$GRID_BASE_URL/quotes/<quoteId>/execute" | jq .

List quotes

列出报价

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/quotes?status=PENDING" | jq .

Get quote details

获取报价详情

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/quotes/<quoteId>" | jq .

undefined

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/quotes/<quoteId>" | jq .

undefined

Same-Currency Transfers

同币种转账

bash

undefined

bash

undefined

Transfer in (external → internal, same currency)

转入（外部账户 → 内部账户，同币种）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "source": {"accountId": "<externalAccountId>"}, "destination": {"accountId": "<internalAccountId>"}, "amount": 10000 }'
"$GRID_BASE_URL/transfer-in" | jq .

Transfer out (internal → external, same currency)

转出（内部账户 → 外部账户，同币种）

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "source": {"accountId": "<internalAccountId>"}, "destination": {"accountId": "<externalAccountId>"}, "amount": 10000 }'
"$GRID_BASE_URL/transfer-out" | jq .

undefined

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "source": {"accountId": "<internalAccountId>"}, "destination": {"accountId": "<externalAccountId>"}, "amount": 10000 }'
"$GRID_BASE_URL/transfer-out" | jq .

undefined

Transactions

交易记录

bash

undefined

bash

undefined

List transactions

列出交易记录

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/transactions?status=PENDING" | jq .

Get transaction details

获取交易详情

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/transactions/<transactionId>" | jq .

Approve incoming payment

批准待处理入账请求

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST
"$GRID_BASE_URL/transactions/<transactionId>/approve" | jq .

Reject incoming payment

拒绝待处理入账请求

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{"reason": "Reason for rejection"}'
"$GRID_BASE_URL/transactions/<transactionId>/reject" | jq .

undefined

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{"reason": "拒绝原因"}'
"$GRID_BASE_URL/transactions/<transactionId>/reject" | jq .

undefined

Receiver Lookup

收款方查询

bash

undefined

bash

undefined

Look up UMA address capabilities

查询UMA地址的收款能力

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/receiver/uma/%24alice%40example.com" | jq .

Look up external account capabilities

查询外部账户的收款能力

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/receiver/external-account/<accountId>" | jq .


**Note:** UMA addresses contain `$` which must be URL-encoded as `%24` in the path.

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
"$GRID_BASE_URL/receiver/external-account/<accountId>" | jq .


**注意：** UMA地址包含`$`符号，在URL路径中必须编码为`%24`。

Sandbox Testing

沙箱测试

bash

undefined

bash

undefined

Fund an internal account in sandbox

为沙箱环境中的内部账户充值

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_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_API_TOKEN_ID:$GRID_API_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

模拟接收UMA支付

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "senderUmaAddress": "$sender@sandbox.grid.uma.money", "receiverUmaAddress": "<receiverAddress>", "receivingCurrencyCode": "USD", "receivingCurrencyAmount": 1000 }'
"$GRID_BASE_URL/sandbox/uma/receive" | jq .

undefined

curl -s -u "$GRID_API_TOKEN_ID:$GRID_API_CLIENT_SECRET"
-X POST -H "Content-Type: application/json"
-d '{ "senderUmaAddress": "$sender@sandbox.grid.uma.money", "receiverUmaAddress": "<receiverAddress>", "receivingCurrencyCode": "USD", "receivingCurrencyAmount": 1000 }'
"$GRID_BASE_URL/sandbox/uma/receive" | jq .

undefined

Payment Flow Patterns

支付流程模式

Grid supports three main payment patterns:

Grid支持三种主要支付模式：

1. Prefunded (Account-Funded)

1. 预资金模式（账户资金支付）

Funds are already in an internal account. Quote executes immediately from existing balance.

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

Use

sourceType: "ACCOUNT"

with an internal account ID.

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

内部账户（USD） → 报价 → 外部账户/UMA（EUR）

使用

sourceType: "ACCOUNT"

并指定内部账户ID。

2. Just-in-Time (Real-Time Funded)

2. 即时资金模式（实时资金支付）

Funds will be provided at execution time. Quote returns

paymentInstructions

with multiple funding options. Grid auto-executes when deposit is received.

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

Use

sourceType: "REALTIME_FUNDING"

with customer ID and currency. Only works with instant settlement methods.

资金将在执行时提供。报价返回包含多种资金选项的

paymentInstructions

。当Grid收到存款时将自动执行。

客户发送加密货币/法币 → Grid检测到存款 → 按锁定汇率自动执行

使用

sourceType: "REALTIME_FUNDING"

并指定客户ID和货币。仅适用于即时结算方式。

3. Same-Currency Transfers

3. 同币种转账

Direct transfers between accounts without currency conversion. No quote needed.

External Account (USD) → Internal Account (USD)  [transfer-in]
Internal Account (USD) → External Account (USD)  [transfer-out]

账户间直接转账，无需货币转换。无需创建报价。

外部账户（USD） → 内部账户（USD）  [transfer-in]
内部账户（USD） → 外部账户（USD）  [transfer-out]

Interactive Payment Workflows

交互式支付工作流

For step-by-step payment workflows, read

references/workflows.md

. Common workflows:

UMA Payment: Receiver lookup -> Quote -> Confirm -> Execute
International Bank Transfer: Create external account -> Receiver lookup -> Quote -> Confirm -> Execute
On-Ramp (Fiat to Crypto): Verify KYC -> Deposit fiat -> Create crypto external account -> Quote with
```
immediatelyExecute
```
Off-Ramp (Crypto to Fiat): Create fiat external account -> Deposit crypto -> Quote -> Execute
Incoming Payment Handling: List pending approvals -> Review -> Approve/Reject

如需分步支付工作流，请阅读

references/workflows.md

。常见工作流：

UMA支付：收款方查询 → 创建报价 → 确认 → 执行
国际银行转账：创建外部账户 → 收款方查询 → 创建报价 → 确认 → 执行
法币入金（法币转加密货币）：验证KYC → 存入法币 → 创建加密货币外部账户 → 使用
```
immediatelyExecute
```
创建报价
法币出金（加密货币转法币）：创建法币外部账户 → 存入加密货币 → 创建报价 → 执行
入账请求处理：列出待批准请求 → 审核 → 批准/拒绝

Real-Time / Just-in-Time Funded Transfers

实时/即时资金转账

Use this flow when the user asks for a "realtime quote" or "just in time" funded transfer. Only use with instant settlement methods — do not use with slow methods like ACH since quotes expire quickly.

Compatible instant methods:

Crypto: BTC (Lightning, Spark), USDC (Solana, Base, Polygon), USDT (Tron)
Fiat: RTP, SEPA Instant, and other instant payment rails

Flow:

Create a quote with
```
sourceType: "REALTIME_FUNDING"
```
. Destination can be an internal account, external account, or UMA address.
The response includes
```
paymentInstructions
```
with multiple funding options simultaneously (e.g., Lightning + Spark for BTC, Solana + Base + Polygon for USDC). Show all options to the user.
Auto-execution: Once the user sends funds to ANY of the provided addresses, Grid automatically detects the deposit and executes at the locked rate. Do NOT call the execute endpoint for JIT quotes. Webhooks sent:
```
ACCOUNT_STATUS
```
on deposit,
```
OUTGOING_PAYMENT
```
on completion.
Quote expiration: Quotes expire in 1-5 minutes. If expired, create a new quote.

当用户请求“实时报价”或“即时资金”转账时使用此流程。仅适用于即时结算方式 — 请勿用于ACH等慢速方式，因为报价会快速过期。

兼容的即时结算方式：

加密货币：BTC（Lightning、Spark）、USDC（Solana、Base、Polygon）、USDT（Tron）
法币：RTP、SEPA Instant及其他即时支付网络

流程：

使用
```
sourceType: "REALTIME_FUNDING"
```
创建报价。目标账户可以是内部账户、外部账户或UMA地址。
响应结果包含
```
paymentInstructions
```
，其中同时提供多种资金选项（例如：BTC的Lightning + Spark，USDC的Solana + Base + Polygon）。需向用户展示所有选项。
自动执行：当用户向任何提供的地址发送资金后，Grid将自动检测到存款并按锁定汇率执行。请勿为JIT报价调用执行端点。触发的Webhook：存款时触发
```
ACCOUNT_STATUS
```
，完成时触发
```
OUTGOING_PAYMENT
```
。
报价过期：报价在1-5分钟内过期。如果过期，请创建新报价。

Best Practices and Common Pitfalls

最佳实践与常见陷阱

Check platform config first: Call
```
GET /config
```
to see supported currencies and required fields
Use smallest currency units: All amounts are in cents/satoshis - use
```
decimals
```
field for display
Handle quote expiration: Quotes expire in 1-5 minutes; be prepared to create new quotes
Choose the right flow: Use prefunded for immediate execution, JIT for crypto/instant rails
Pipe through jq: Always append
```
| jq .
```
for readable output, or
```
| jq -r .field
```
to extract specific values
URL-encode special characters: UMA addresses contain
```
$
```
— encode as
```
%24
```
in URL paths
Always include destination currency in quotes: When specifying a destination account, you MUST include
```
currency
```
in the destination object even though the external account already has a currency
Individual beneficiary fields are all required: For
```
beneficiaryType: "INDIVIDUAL"
```
, you MUST include
```
fullName
```
,
```
birthDate
```
(YYYY-MM-DD), and
```
nationality
```
(2-letter code) in the
```
beneficiary
```
object
Use correct Nigerian field names: Use
```
bankName
```
(NOT
```
bankCode
```
) and include
```
purposeOfPayment
```
Don't forget country-specific required fields: Brazil (PIX) requires
```
pixKey
```
,
```
pixKeyType
```
, and
```
taxId
```
; Europe (IBAN) requires
```
swiftBic
```

先检查平台配置：调用
```
GET /config
```
查看支持的货币和必填字段
使用最小货币单位：所有金额均为美分/聪 — 使用
```
decimals
```
字段转换为显示格式
处理报价过期：报价在1-5分钟内过期；需准备创建新报价
选择正确的流程：预资金模式适用于即时执行，JIT模式适用于加密货币/即时结算方式
通过jq输出：始终追加
```
| jq .
```
以获得可读格式，或使用
```
| jq -r .field
```
提取特定值
URL编码特殊字符：UMA地址包含
```
$
```
— 在URL路径中需编码为
```
%24
```
报价中始终包含目标货币：指定目标账户时，即使外部账户已有货币，也必须在目标对象中包含
```
currency
```
字段
个人收款方字段均为必填：对于
```
beneficiaryType: "INDIVIDUAL"
```
，必须在
```
beneficiary
```
对象中包含
```
fullName
```
、
```
birthDate
```
（YYYY-MM-DD格式）和
```
nationality
```
（两位国家代码）
使用正确的尼日利亚字段名称：使用
```
bankName
```
（而非
```
bankCode
```
）并包含
```
purposeOfPayment
```
不要忘记特定国家的必填字段：巴西（PIX）需要
```
pixKey
```
、
```
pixKeyType
```
和
```
taxId
```
；欧洲（IBAN）需要
```
swiftBic
```

Error Handling

错误处理

API responses follow this structure on success:

json

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

On error:

json

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

The HTTP status code indicates the error category (400 for bad input, 401 for auth issues, 404 for not found, etc.).

成功时API响应遵循以下结构：

json

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

错误时：

json

{
  "code": "ERROR_CODE",
  "message": "易读的错误信息"
}

HTTP状态码表示错误类别（400表示输入错误，401表示认证问题，404表示资源不存在等）。

Common Error Codes

常见错误码

Quote/Transfer Errors:

```
QUOTE_EXPIRED
```
- Quote timed out; create a new quote
```
INSUFFICIENT_BALANCE
```
- Check internal account balance before transfer
```
INVALID_BANK_ACCOUNT
```
- Validate field formats per country requirements
```
QUOTE_EXECUTION_FAILED
```
- Transient error; retry with exponential backoff

Incoming Payment Errors:

```
PAYMENT_APPROVAL_TIMED_OUT
```
- Webhook approval not received within 5 seconds
```
PAYMENT_APPROVAL_WEBHOOK_ERROR
```
- Webhook returned error

Validation Errors:

```
INVALID_INPUT
```
- Check required fields; the
```
reason
```
field has details
```
MISSING_MANDATORY_USER_INFO
```
- Customer or sender info missing required fields

Always check the HTTP status code and report errors clearly to the user.

报价/转账错误：

```
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状态码，并向用户清晰报告错误信息。

grid-api

Original

Translation

Grid API Skill

Grid API Skill

Supporting References

参考资料

Key Concepts

核心概念

Entities

实体

Account Types

账户类型

Account Status Lifecycle

账户状态生命周期

Currency & Amounts

货币与金额

Configuration

配置

Base URL

基础URL

Documentation Resources

文档资源

Making API Calls

发起API调用

API Operations

API操作

Platform Configuration

平台配置

Get platform config (currencies, limits)

获取平台配置（支持的货币、限额）

Update platform config (e.g., set webhook endpoint)

更新平台配置（例如：设置webhook端点）

Customer Management

客户管理

List customers

列出客户

Get customer details

获取客户详情

Create customer

创建客户

Update customer (customerType is required)

更新客户（customerType为必填项）

Delete customer

删除客户

Generate KYC link (GET with query params)

生成KYC链接（带查询参数的GET请求）

Account Management

账户管理

List customer internal accounts

列出客户内部账户

List platform internal accounts

列出平台内部账户

List customer external accounts

列出客户外部账户

Create external account (example: Mexico CLABE - Individual)

创建外部账户（示例：墨西哥CLABE - 个人账户）

Quotes (Cross-Currency Transfers)

报价（跨币种转账）

Account-funded to UMA: Use when funds are already in an internal account

账户资金支付至UMA：适用于资金已在内部账户的场景

Account-funded to external account: IMPORTANT - always include destination currency

账户资金支付至外部账户：重要提示 - 必须包含目标货币

Real-time/JIT funded: Returns paymentInstructions for funding

实时/JIT资金支付：返回包含资金选项的paymentInstructions

Execute a quote

执行报价

List quotes

列出报价

Get quote details

获取报价详情

Same-Currency Transfers

同币种转账

Transfer in (external → internal, same currency)

转入（外部账户 → 内部账户，同币种）

Transfer out (internal → external, same currency)

转出（内部账户 → 外部账户，同币种）

Transactions

交易记录

List transactions