Back to Details

onchain-pay-open-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Binance Onchain-Pay Open API Skill

Binance Onchain-Pay 开放API Skill

Call Binance Onchain-Pay Open API endpoints with automatic RSA SHA256 request signing.
调用 Binance Onchain-Pay 开放API接口，自动完成 RSA SHA256 请求签名。

Use Cases & Scenarios

使用场景

This skill is designed for the following scenarios:
该 Skill 适用于以下场景：

1. 💳 Fiat-to-Crypto Purchase & Send

1. 💳 法币兑加密货币购买并发送

When to use: User wants to buy crypto with fiat currency and send directly to an external on-chain wallet address
  • Buy USDT with USD/EUR/TWD using credit card → Send to MetaMask address on BSC
  • Purchase BTC with Google Pay → Transfer to hardware wallet
  • Buy USDC with P2P → Send to DeFi protocol contract address
Key APIs: 
trading-pairs
→ 
payment-method-list
→ 
estimated-quote
→ 
pre-order
适用场景：用户希望用法币购买加密货币并直接发送到外部链上钱包地址
  • 使用信用卡以 USD/EUR/TWD 购买 USDT → 发送到 BSC 链上的 MetaMask 地址
  • 使用 Google Pay 购买 BTC → 转账到硬件钱包
  • 通过 P2P 购买 USDC → 发送到 DeFi 协议合约地址
核心API：
trading-pairs
→ 
payment-method-list
→ 
estimated-quote
→ 
pre-order

2. 🔄 Direct Crypto Transfer (Send Primary)

2. 🔄 加密货币直接转账（发送优先）

When to use: User has crypto in Binance account and wants to send to external address
  • Send existing USDT from Binance Spot to friend's wallet address
  • Transfer ETH to Uniswap contract for trading
  • Move crypto from Binance to self-custodial wallet (Trust Wallet, Ledger, etc.)
Key APIs: 
pre-order
with 
SEND_PRIMARY
customization
适用场景：用户 Binance 账户中持有加密货币，想要发送到外部地址
  • 将 Binance 现货账户中已有的 USDT 发送到朋友的钱包地址
  • 转账 ETH 到 Uniswap 合约进行交易
  • 将加密货币从 Binance 转移到自托管钱包（Trust Wallet、Ledger等）
核心API：配置 
SEND_PRIMARY
参数的 
pre-order
接口

3. 🔗 Cross-Chain Bridge Operations

3. 🔗 跨链桥操作

When to use: User needs to buy crypto on one chain and transfer to another network
  • Buy USDC on Ethereum → Bridge to Polygon for lower fees
  • Purchase tokens on BSC → Transfer to Base network
  • Fiat to crypto on Solana → Send to Arbitrum for DeFi
Key APIs: 
crypto-network
→ 
pre-order
with network selection
适用场景：用户需要在某条链上购买加密货币，再转账到另一个网络
  • 在以太坊链上购买 USDC → 跨桥到 Polygon 以降低手续费
  • 在 BSC 链上购买代币 → 转账到 Base 网络
  • 用法币在 Solana 链上购买加密货币 → 发送到 Arbitrum 用于 DeFi 操作
核心API：
crypto-network
→ 配置网络选择的 
pre-order
接口

4. 🏪 Merchant Payment Integration

4. 🏪 商户支付集成

When to use: Integrate crypto payment gateway for e-commerce or services
  • Accept fiat payments and auto-convert to crypto
  • Enable "Pay with Crypto" checkout flow
  • Process subscription payments with crypto
Key APIs: 
pre-order
with 
externalOrderId
tracking
适用场景：为电商或服务类场景集成加密货币支付网关
  • 接受法币支付并自动转换为加密货币
  • 支持「加密货币支付」的结算流程
  • 处理加密货币订阅付款
核心API：配置 
externalOrderId
跟踪的 
pre-order
接口

5. 🤖 Smart Contract Interaction (Onchain-Pay Easy)

5. 🤖 智能合约交互（Onchain-Pay 便捷模式）

When to use: Buy crypto and execute smart contract in one transaction
  • Buy USDT and deposit to lending protocol
  • Purchase tokens and stake in DeFi pool
  • Fiat on-ramp directly to GameFi or NFT marketplace
Key APIs: 
pre-order
with 
ON_CHAIN_PROXY_MODE
customization
适用场景：购买加密货币并在单交易中执行智能合约
  • 购买 USDT 并存入借贷协议
  • 购买代币并质押到 DeFi 矿池
  • 法币入金直接到 GameFi 或 NFT 市场
核心API：配置 
ON_CHAIN_PROXY_MODE
参数的 
pre-order
接口

6. 📊 Query & Monitoring

6. 📊 查询与监控

When to use: Check order status, available networks, or payment methods
  • Monitor order processing status (pending, completed, failed)
  • List supported fiat currencies and cryptocurrencies
  • Check available payment methods for specific country/amount
  • Verify network fees and limits
Key APIs: 
order
, 
crypto-network
, 
trading-pairs
, 
payment-method-list
适用场景：查看订单状态、可用网络或支付方式
  • 监控订单处理状态（待处理、已完成、失败）
  • 列出支持的法币和加密货币币种
  • 查询特定国家/金额可用的支付方式
  • 核验网络手续费和限额
核心API：
order
、
crypto-network
、
trading-pairs
、
payment-method-list

Quick Reference

快速参考

EndpointAPI PathRequired ParamsOptional Params
Payment Method List (v1)
papi/v1/ramp/connect/buy/payment-method-list
fiatCurrency, cryptoCurrency, totalAmount, amountTypenetwork, contractAddress
Payment Method List (v2)
papi/v2/ramp/connect/buy/payment-method-list
(none)lang
Trading Pairs
papi/v1/ramp/connect/buy/trading-pairs
(none)(none)
Estimated Quote
papi/v1/ramp/connect/buy/estimated-quote
fiatCurrency, requestedAmount, payMethodCode, amountTypecryptoCurrency, contractAddress, address, network
Pre-order
papi/v1/ramp/connect/gray/buy/pre-order
externalOrderId, merchantCode, merchantName, tsfiatCurrency, fiatAmount, cryptoCurrency, requestedAmount, amountType, address, network, payMethodCode, payMethodSubCode, redirectUrl, failRedirectUrl, redirectDeepLink, failRedirectDeepLink, customization, destContractAddress, destContractABI, destContractParams, affiliateCode, gtrTemplateCode, contractAddress
Get Order
papi/v1/ramp/connect/order
externalOrderId(none)
Crypto Network
papi/v1/ramp/connect/crypto-network
(none)(none)
P2P Trading Pairs
papi/v1/ramp/connect/buy/p2p/trading-pairs
(none)fiatCurrency
EndpointAPI PathRequired ParamsOptional Params
支付方式列表（v1）
papi/v1/ramp/connect/buy/payment-method-list
fiatCurrency, cryptoCurrency, totalAmount, amountTypenetwork, contractAddress
支付方式列表（v2）
papi/v2/ramp/connect/buy/payment-method-list
无lang
交易对列表
papi/v1/ramp/connect/buy/trading-pairs
无无
预估报价
papi/v1/ramp/connect/buy/estimated-quote
fiatCurrency, requestedAmount, payMethodCode, amountTypecryptoCurrency, contractAddress, address, network
预下单
papi/v1/ramp/connect/gray/buy/pre-order
externalOrderId, merchantCode, merchantName, tsfiatCurrency, fiatAmount, cryptoCurrency, requestedAmount, amountType, address, network, payMethodCode, payMethodSubCode, redirectUrl, failRedirectUrl, redirectDeepLink, failRedirectDeepLink, customization, destContractAddress, destContractABI, destContractParams, affiliateCode, gtrTemplateCode, contractAddress
订单查询
papi/v1/ramp/connect/order
externalOrderId无
加密货币网络列表
papi/v1/ramp/connect/crypto-network
无无
P2P交易对列表
papi/v1/ramp/connect/buy/p2p/trading-pairs
无fiatCurrency

How to Execute a Request

如何执行请求

Step 1: Gather credentials

步骤1：获取凭证

Use the default account (prod) unless the user specifies otherwise. You need:
  • BASE_URL: API base URL
  • CLIENT_ID: Client identifier
  • API_KEY: The sign access token
  • PEM_PATH: Absolute path to the RSA private key PEM file
Use the account marked 
(default)
in 
.local.md
.
除非用户指定其他账户，否则使用默认账户（prod）。你需要：
  • BASE_URL：API基础地址
  • CLIENT_ID：客户端标识
  • API_KEY：签名访问令牌
  • PEM_PATH：RSA私钥PEM文件的绝对路径
使用 
.local.md
中标记为 
(default)
的账户。

Step 2: Build the JSON body

步骤2：构建JSON请求体

Build a compact JSON body from user-specified parameters. Remove any parameters the user did not provide.
IMPORTANT: Address and Network Validation
  • address
    (destination wallet address) and 
    network
    (blockchain network) are REQUIRED for all pre-order requests
  • If the user has configured 
    Default Address
    and 
    Default Network
    in 
    .local.md
    , use them automatically
  • If not configured or not provided by user, ASK the user to provide both values before proceeding
根据用户指定的参数构建精简的JSON请求体，移除所有用户未提供的参数。
重要提示：地址和网络校验
  • 所有预下单请求都必须提供 
    address
    （目标钱包地址）和 
    network
    （区块链网络）参数
  • 如果用户已经在 
    .local.md
    中配置了「默认地址」和「默认网络」，则自动使用这两个值
  • 如果没有配置或用户未提供这两个值，在继续操作前请先询问用户获取

Step 3: Sign and call using the bundled script

步骤3：使用内置脚本签名并调用

bash
bash <skill_path>/scripts/sign_and_call.sh \
  "<BASE_URL>" \
  "<API_PATH>" \
  "<CLIENT_ID>" \
  "<API_KEY>" \
  "<PEM_PATH>" \
  '<JSON_BODY>'
bash
bash <skill_path>/scripts/sign_and_call.sh \
  "<BASE_URL>" \
  "<API_PATH>" \
  "<CLIENT_ID>" \
  "<API_KEY>" \
  "<PEM_PATH>" \
  '<JSON_BODY>'

Step 4: Return results

步骤4：返回结果

Display the JSON response to the user in a readable format.
将JSON响应以易读的格式展示给用户。

Authentication

鉴权说明

See 
references/authentication.md
 for full signing details.
Summary:
  1. Payload = 
    JSON_BODY
    + 
    TIMESTAMP
    (milliseconds)
  2. Sign payload with RSA SHA256 using PEM private key
  3. Base64 encode the signature (single line)
  4. Send as POST with headers: 
    X-Tesla-ClientId
    , 
    X-Tesla-SignAccessToken
    , 
    X-Tesla-Signature
    , 
    X-Tesla-Timestamp
    , 
    Content-Type: application/json
完整的签名细节请查看 
references/authentication.md
。
摘要说明：
  1. 签名载荷 = 
    JSON_BODY
    + 
    TIMESTAMP
    （毫秒级时间戳）
  2. 使用PEM私钥通过RSA SHA256算法对载荷签名
  3. 对签名结果做Base64编码（单行格式）
  4. 发送POST请求，携带以下请求头：
    X-Tesla-ClientId
    、
    X-Tesla-SignAccessToken
    、
    X-Tesla-Signature
    、
    X-Tesla-Timestamp
    、
    Content-Type: application/json

Parameters Reference

参数参考

Payment Method List v1 (
buy/payment-method-list
)

支付方式列表v1（
buy/payment-method-list
）

ParameterTypeRequiredDescription
fiatCurrencystringYesFiat currency code (e.g., 
USD
, 
EUR
, 
BRL
, 
UGX
)
cryptoCurrencystringYesCrypto currency code (e.g., 
BTC
, 
USDT
, 
USDC
, 
SEI
)
totalAmountnumberYesAmount value
amountTypenumberYes
1
= fiat amount, 
2
= crypto amount
networkstringNoBlockchain network (e.g., 
BSC
, 
ETH
, 
SOL
, 
BASE
, 
SEI
)
contractAddressstringNoToken contract address (required for non-native tokens)
参数类型必填描述
fiatCurrencystring是法币币种编码（如 
USD
、
EUR
、
BRL
、
UGX
）
cryptoCurrencystring是加密货币币种编码（如 
BTC
、
USDT
、
USDC
、
SEI
）
totalAmountnumber是金额数值
amountTypenumber是
1
= 法币金额，
2
= 加密货币金额
networkstring否区块链网络（如 
BSC
、
ETH
、
SOL
、
BASE
、
SEI
）
contractAddressstring否代币合约地址（非原生代币必填）

Payment Method List v2 (
v2/buy/payment-method-list
)

支付方式列表v2（
v2/buy/payment-method-list
）

Get all available payment methods without specifying fiat/crypto parameters. Simplified version of v1.
ParameterTypeRequiredDescription
langstringNoLanguage code for localized payment method names (e.g., 
en
, 
cn
, 
es
)
Differences from v1:
  • Simpler: No need to specify fiatCurrency, cryptoCurrency, or amount
  • Comprehensive: Returns all available payment methods for the merchant
  • Use case: Useful for displaying all options before user input
Response Format: Same as v1, returns list of payment methods with their limits and properties.
无需指定法币/加密货币参数即可获取所有可用支付方式，是v1的简化版本。
参数类型必填描述
langstring否支付方式名称本地化的语言编码（如 
en
、
cn
、
es
）
与v1的差异：
  • 更简单：无需指定法币币种、加密货币币种或金额
  • 更全面：返回商户可用的所有支付方式
  • 适用场景：适合在用户输入前展示所有可选支付方式
响应格式：与v1一致，返回支付方式列表及对应限额和属性。

Estimated Quote (
buy/estimated-quote
)

预估报价（
buy/estimated-quote
）

ParameterTypeRequiredDescription
fiatCurrencystringYesFiat currency code
cryptoCurrencystringNoCrypto currency code (optional if contractAddress provided)
requestedAmountnumberYesAmount value
payMethodCodestringYesPayment method (e.g., 
BUY_CARD
, 
BUY_GOOGLE_PAY
, 
BUY_P2P
, 
BUY_WALLET
)
amountTypenumberYes
1
= fiat amount, 
2
= crypto amount
networkstringYes*Blockchain network (can use default from 
.local.md
)
contractAddressstringNoToken contract address
addressstringYes*Destination wallet address for receiving crypto
* Recommended: These parameters should be provided. If not specified by user, check 
.local.md
for defaults. If no defaults exist, ask user before proceeding.
参数类型必填描述
fiatCurrencystring是法币币种编码
cryptoCurrencystring否加密货币币种编码（如果提供了contractAddress则可选）
requestedAmountnumber是金额数值
payMethodCodestring是支付方式（如 
BUY_CARD
、
BUY_GOOGLE_PAY
、
BUY_P2P
、
BUY_WALLET
）
amountTypenumber是
1
= 法币金额，
2
= 加密货币金额
networkstring是*区块链网络（可使用 
.local.md
中的默认值）
contractAddressstring否代币合约地址
addressstring是*接收加密货币的目标钱包地址
* 推荐提供这些参数。如果用户未指定，请检查 
.local.md
中的默认值。如果没有默认值，请在继续操作前询问用户。

Pre-order (
buy/pre-order
)

预下单（
buy/pre-order
）

Create a buy pre-order and return the redirect link for payment.
ParameterTypeRequiredDescription
externalOrderIdstringYesPartner's unique order ID (must be unique)
merchantCodestringYesMerchant code (e.g., 
connect-gray
)
merchantNamestringYesMerchant display name (e.g., 
GrayTest
)
tsnumberYesCurrent timestamp in milliseconds
fiatCurrencystringNo*Fiat currency code (e.g., 
TWD
, 
USD
, 
EUR
)
fiatAmountnumberNo*Fiat amount to spend
cryptoCurrencystringNo*Crypto currency to buy (e.g., 
USDT
, 
BTC
, 
ETH
)
requestedAmountnumberNo*Amount value (fiat or crypto based on amountType)
amountTypenumberNo*
1
= fiat amount, 
2
= crypto amount
addressstringNoDestination wallet address for receiving crypto
networkstringNoBlockchain network (e.g., 
BSC
, 
ETH
, 
SOL
)
payMethodCodestringNoPayment method code (e.g., 
BUY_CARD
, 
BUY_P2P
, 
BUY_GOOGLE_PAY
, 
BUY_APPLE_PAY
, 
BUY_PAYPAL
, 
BUY_WALLET
, 
BUY_REVOLUT
)
payMethodSubCodestringNoPayment method sub-code (e.g., 
card
, 
GOOGLE_PAY
, 
WECHAT
)
redirectUrlstringNoSuccess redirect URL
failRedirectUrlstringNoFailure redirect URL
redirectDeepLinkstringNoDeep link for success (mobile apps)
failRedirectDeepLinkstringNoDeep link for failure (mobile apps)
customizationobjectNoCustom configuration object (see Customization section below)
destContractAddressstringNoDestination contract address (for Onchain-Pay Easy mode)
destContractABIstringNoContract ABI name (for Onchain-Pay Easy mode)
destContractParamsobjectNoContract parameters (for Onchain-Pay Easy mode)
affiliateCodestringNoAffiliate code for commission tracking
gtrTemplateCodestringNoGTR template code (e.g., 
OTHERS
)
contractAddressstringNoToken contract address (for non-native tokens)
* Either 
fiatAmount
or (
requestedAmount
+ 
amountType
) should be provided. If 
fiatCurrency
is not provided, the system will auto-select available fiat currencies.
Response Example:
json
{
  "code": "000000",
  "message": "success",
  "data": {
    "link": "https://app.binance.com/uni-qr/ccnt?...",
    "linkExpireTime": 1772852565045
  },
  "success": true
}
创建购买预订单并返回支付跳转链接。
参数类型必填描述
externalOrderIdstring是合作方唯一订单ID（必须唯一）
merchantCodestring是商户编码（如 
connect-gray
）
merchantNamestring是商户展示名称（如 
GrayTest
）
tsnumber是当前毫秒级时间戳
fiatCurrencystring否*法币币种编码（如 
TWD
、
USD
、
EUR
）
fiatAmountnumber否*消费的法币金额
cryptoCurrencystring否*要购买的加密货币（如 
USDT
、
BTC
、
ETH
）
requestedAmountnumber否*金额数值（根据amountType决定是法币还是加密货币金额）
amountTypenumber否*
1
= 法币金额，
2
= 加密货币金额
addressstring否接收加密货币的目标钱包地址
networkstring否区块链网络（如 
BSC
、
ETH
、
SOL
）
payMethodCodestring否支付方式编码（如 
BUY_CARD
、
BUY_P2P
、
BUY_GOOGLE_PAY
、
BUY_APPLE_PAY
、
BUY_PAYPAL
、
BUY_WALLET
、
BUY_REVOLUT
）
payMethodSubCodestring否支付方式子编码（如 
card
、
GOOGLE_PAY
、
WECHAT
）
redirectUrlstring否成功跳转地址
failRedirectUrlstring否失败跳转地址
redirectDeepLinkstring否成功跳转Deep Link（移动端应用使用）
failRedirectDeepLinkstring否失败跳转Deep Link（移动端应用使用）
customizationobject否自定义配置对象（参考下方自定义配置章节）
destContractAddressstring否目标合约地址（Onchain-Pay便捷模式使用）
destContractABIstring否合约ABI名称（Onchain-Pay便捷模式使用）
destContractParamsobject否合约参数（Onchain-Pay便捷模式使用）
affiliateCodestring否用于佣金跟踪的推广码
gtrTemplateCodestring否GTR模板编码（如 
OTHERS
）
contractAddressstring否代币合约地址（非原生代币使用）
* 需要提供 
fiatAmount
或者（
requestedAmount
+ 
amountType
）两者其一。如果未提供 
fiatCurrency
，系统会自动选择可用的法币币种。
响应示例：
json
{
  "code": "000000",
  "message": "success",
  "data": {
    "link": "https://app.binance.com/uni-qr/ccnt?...",
    "linkExpireTime": 1772852565045
  },
  "success": true
}

Get Order (
order
)

订单查询（
order
）

ParameterTypeRequiredDescription
externalOrderIdstringYesThe external order ID to query
参数类型必填描述
externalOrderIdstring是要查询的外部订单ID

Customization Options

自定义配置选项

The 
customization
field in pre-order API accepts various flags to customize the buy flow behavior. Each merchant must have the corresponding permission configured in 
db.merchant_info
table.
预下单API中的
customization
字段支持多种配置标记，可自定义购买流程行为。每个商户需要在
db.merchant_info
表中配置对应的权限才能使用。

Available Customization Flags

可用自定义配置标记

FlagCodeTypeAvailabilityDescriptionUse Case
LOCK_ORDER_ATTRIBUTES
1arrayOpen API ✓Lock specific order attributes so users cannot modify them. Values: 
1
=fiat currency, 
2
=crypto currency, 
3
=amount, 
4
=payment method, 
5
=network, 
6
=address, 
7
=fiat amount, 
8
=crypto amount		Fixed-parameter orders
SKIP_CASHIER
2booleanOpen API ✓Skip the cashier page and proceed directly to payment. Reduces user friction in the checkout flow.Streamlined payment experience
AUTO_REDIRECTION
3booleanOpen API ✓Automatically redirect to 
redirectUrl
after order completion without showing success page.		Seamless user experience
HIDE_SEND
6booleanOpen API ✓Hide the "Send" tab in the UI. Useful when only buy flow is needed.Buy-only integration
SEND_PRIMARY
7booleanOpen API ✓Enable Send Crypto feature. If user's Binance balance is insufficient, auto-trigger buy flow first.Send crypto to external address
MERCHANT_DISPLAY_NAME
8stringOpen API ✓Override the display name shown to users in the UI.Custom branding
NET_RECEIVE
9booleanOpen API ✓User receives net amount after deducting all fees. Total cost is more transparent.Better UX for showing final received amount
P2P_EXPRESS
10booleanOpen API ✓Enable P2P Express mode for faster P2P order matching.Quick P2P transactions
OPEN_NETWORK
11booleanWeb3 onlyAllow users to select different networks. Default is locked to pre-selected network. Note: Currently only available for Web3 entrance, not available for Open API.Multi-network support (Web3 only)
ON_CHAIN_PROXY_MODE
12booleanOpen API ✓Enable Onchain-Pay Easy mode. After buying crypto, Onchain-Pay will execute smart contract interaction instead of direct withdrawal to user wallet. Requires 
destContractAddress
, 
destContractABI
, and 
destContractParams
.		Fiat to Smart Contract integration
SEND_PRIMARY_FLEXIBLE
13booleanOpen API ✓Flexible Send Primary mode with more options.Advanced send crypto scenarios
标记名编码类型可用性描述适用场景
LOCK_ORDER_ATTRIBUTES
1array开放API ✓锁定指定订单属性，用户无法修改。可选值：
1
=法币币种、
2
=加密货币币种、
3
=金额、
4
=支付方式、
5
=网络、
6
=地址、
7
=法币金额、
8
=加密货币金额		固定参数订单
SKIP_CASHIER
2boolean开放API ✓跳过收银台页面直接进入支付环节，降低结算流程的用户摩擦简化支付体验
AUTO_REDIRECTION
3boolean开放API ✓订单完成后自动跳转到
redirectUrl
，无需展示成功页面		无缝用户体验
HIDE_SEND
6boolean开放API ✓隐藏界面中的「发送」标签，适合仅需要购买流程的场景仅购买功能集成
SEND_PRIMARY
7boolean开放API ✓启用加密货币发送功能。如果用户Binance余额不足，会自动先触发购买流程发送加密货币到外部地址
MERCHANT_DISPLAY_NAME
8string开放API ✓覆盖界面中展示给用户的商户名称自定义品牌展示
NET_RECEIVE
9boolean开放API ✓用户收到扣除所有手续费后的净额，总花费更透明优化展示最终到账金额的用户体验
P2P_EXPRESS
10boolean开放API ✓启用P2P快捷模式，加快P2P订单匹配速度快速P2P交易
OPEN_NETWORK
11boolean仅Web3可用允许用户选择不同网络，默认锁定为预选择的网络。注意：目前仅支持Web3入口，开放API不可用多网络支持（仅Web3）
ON_CHAIN_PROXY_MODE
12boolean开放API ✓启用Onchain-Pay便捷模式。购买加密货币后，Onchain-Pay会执行智能合约交互，而非直接提现到用户钱包。需要搭配
destContractAddress
、
destContractABI
和
destContractParams
参数使用		法币到智能合约集成
SEND_PRIMARY_FLEXIBLE
13boolean开放API ✓灵活的发送优先模式，支持更多配置选项高级加密货币发送场景

Customization Examples

自定义配置示例

Example 1: Basic Card Payment
json
{
  "customization": {}
}
Example 2: Onchain-Pay Easy (On-Chain Proxy)
json
{
  "customization": {
    "ON_CHAIN_PROXY_MODE": true,
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  },
  "destContractAddress": "0x128...974",
  "destContractABI": "depositFor",
  "destContractParams": {
    "accountType": 2
  }
}
Example 3: Send Crypto
json
{
  "customization": {
    "SEND_PRIMARY_FLEXIBLE": true,
    "SEND_PRIMARY": true
  }
}
Example 4: P2P with Auto Redirection
json
{
  "customization": {
    "AUTO_REDIRECTION": true,
    "P2P_EXPRESS": true
  }
}
Example 5: Lock Order Attributes
json
{
  "customization": {
    "LOCK_ORDER_ATTRIBUTES": [2, 3, 6, 7, 8],
    "MERCHANT_DISPLAY_NAME": "My Custom Brand"
  }
}
Lock attribute codes:
  • 2
    = Crypto currency
  • 3
    = Amount
  • 6
    = Address
  • 7
    = Fiat amount
  • 8
    = Crypto amount
Example 6: Net Receive Mode
json
{
  "customization": {
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  }
}
Example 7: Hide Send Tab
json
{
  "customization": {
    "HIDE_SEND": true
  }
}
Example 8: Skip Cashier (Direct Payment)
json
{
  "customization": {
    "SKIP_CASHIER": true
  }
}
示例1：基础银行卡支付
json
{
  "customization": {}
}
示例2：Onchain-Pay便捷模式（链上代理）
json
{
  "customization": {
    "ON_CHAIN_PROXY_MODE": true,
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  },
  "destContractAddress": "0x128...974",
  "destContractABI": "depositFor",
  "destContractParams": {
    "accountType": 2
  }
}
示例3：加密货币发送
json
{
  "customization": {
    "SEND_PRIMARY_FLEXIBLE": true,
    "SEND_PRIMARY": true
  }
}
示例4：带自动跳转的P2P支付
json
{
  "customization": {
    "AUTO_REDIRECTION": true,
    "P2P_EXPRESS": true
  }
}
示例5：锁定订单属性
json
{
  "customization": {
    "LOCK_ORDER_ATTRIBUTES": [2, 3, 6, 7, 8],
    "MERCHANT_DISPLAY_NAME": "My Custom Brand"
  }
}
锁定属性编码说明：
  • 2
    = 加密货币币种
  • 3
    = 金额
  • 6
    = 地址
  • 7
    = 法币金额
  • 8
    = 加密货币金额
示例6：净额到账模式
json
{
  "customization": {
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  }
}
示例7：隐藏发送标签
json
{
  "customization": {
    "HIDE_SEND": true
  }
}
示例8：跳过收银台（直接支付）
json
{
  "customization": {
    "SKIP_CASHIER": true
  }
}

Important Notes

重要注意事项

  1. Permission Required: Each customization flag requires merchant permission. Check with admin if a flag is not working.
  2. Onchain-Pay Easy: Only supported on BSC network currently. Requires contract integration.
  3. Validation: Invalid customization values (e.g., 
    null
    for 
    MERCHANT_DISPLAY_NAME
    ) will return 
    ILLEGAL_CUSTOMIZATION_VALUE
    error.
  4. Combinations: Some flags work together (e.g., 
    NET_RECEIVE
    + 
    SEND_PRIMARY
    ), while others are independent.
  5. Testing: Use test accounts (
    connect-gray
    ) for testing customization flags before production.
  6. Internal Flags: 
    OPERATION
    (code 4) and 
    SKIP_WITHDRAW
    (code 5) are internal use only and should NOT be passed from merchant side.
  7. OPEN_NETWORK: Currently only available for Web3 entrance, not available for Open API. Do not use this flag in Open API pre-order requests.
  8. Flag Order: Flags are ordered by their internal code (1-13). The code number is used internally for identification.
  1. 需要权限：每个自定义配置标记都需要商户拥有对应权限，如果标记不生效请联系管理员确认。
  2. Onchain-Pay便捷模式：目前仅支持BSC网络，需要完成合约集成。
  3. 校验规则：无效的自定义配置值（比如
    MERCHANT_DISPLAY_NAME
    传
    null
    ）会返回
    ILLEGAL_CUSTOMIZATION_VALUE
    错误。
  4. 组合使用：部分标记可以搭配使用（比如
    NET_RECEIVE
    + 
    SEND_PRIMARY
    ），其他标记相互独立。
  5. 测试要求：上线前请使用测试账户（
    connect-gray
    ）测试自定义配置标记。
  6. 内部标记：
    OPERATION
    （编码4）和
    SKIP_WITHDRAW
    （编码5）仅内部使用，商户侧不允许传递。
  7. OPEN_NETWORK：目前仅支持Web3入口，开放API不可用，不要在开放API预下单请求中使用该标记。
  8. 标记顺序：标记按内部编码（1-13）排序，编码用于内部识别。

Security

安全规范

Credential Display Rules

凭证展示规则

  • API Key: Show first 5 + last 4 characters only (e.g., 
    2zefb...06h
    )
  • PEM Private Key: NEVER display content. NEVER display the file path.
  • Client ID: Can be displayed in full.
  • Outbound Requests: NEVER send API Key, Private Key, or any credentials to URLs outside the Base URL configured in 
    .local.md
    .
  • File Path Privacy: NEVER display the PEM private key file path to the user in any output or logs.
  • API Key：仅展示前5位+后4位（比如 
    2zefb...06h
    ）
  • PEM私钥：绝对不要展示内容，也不要展示文件路径。
  • Client ID：可以完整展示。
  • 出站请求：绝对不要将API Key、私钥或任何凭证发送到
    .local.md
    中配置的Base URL以外的地址。
  • 文件路径隐私：绝对不要在任何输出或日志中向用户展示PEM私钥的文件路径。

Credential Storage

凭证存储

Credentials are stored in a 
.local.md
file in the skill directory. This file is user-specific and should NOT be distributed.
Read the 
.local.md
file from the same directory as this SKILL.md to load credentials.
If 
.local.md
does not exist or the requested account is not found, ask the user to provide:
  1. Base URL
  2. Client ID
  3. API Key
  4. PEM file path (absolute path)
Then offer to save them to 
.local.md
for future use.
凭证存储在Skill目录下的
.local.md
文件中，该文件是用户专属的，不应该分发。
从当前SKILL.md所在目录读取
.local.md
文件加载凭证。
如果
.local.md
不存在，或者找不到请求的账户，请询问用户提供：
  1. Base URL
  2. Client ID
  3. API Key
  4. PEM文件路径（绝对路径）
之后可询问用户是否要将这些信息保存到
.local.md
以便后续使用。

.local.md
Format

.local.md
格式

markdown
undefined
markdown
undefined

Onchain-Pay Accounts

Onchain-Pay 账户

prod (default)

prod (default)

  • Base URL: https://api.commonservice.io
  • Client ID: your-client-id
  • API Key: your-api-key
  • PEM Path: /absolute/path/to/your/private.pem
  • Default Network: your-preferred-network
  • Default Address: your-wallet-address
  • Description: Production account

The account marked `(default)` is used automatically. You can define multiple accounts and switch by telling Claude the account name.

---
  • Base URL: https://api.commonservice.io
  • Client ID: your-client-id
  • API Key: your-api-key
  • PEM Path: /absolute/path/to/your/private.pem
  • Default Network: your-preferred-network
  • Default Address: your-wallet-address
  • Description: 生产环境账户

标记为`(default)`的账户会被自动使用。你可以定义多个账户，通过告诉Claude账户名来切换使用。

---

User Agent Header

User-Agent 请求头

Include 
User-Agent
header with the following string: 
onchain-pay-open-api/0.1.0 (Skill)
请求中需要携带
User-Agent
头，值为：
onchain-pay-open-api/0.1.0 (Skill)

Agent Behavior

Agent 行为规范

  1. If the user asks to call an Onchain-Pay API endpoint, identify which endpoint from the Quick Reference table
  2. Ask for any missing required parameters
  3. Use stored credentials if available, otherwise ask the user
  4. Execute the request using the bundled 
    scripts/sign_and_call.sh
  5. Display the response in a readable format
  6. If the request fails, show the error and suggest fixes
  1. 如果用户要求调用Onchain-Pay API接口，先从快速参考表中识别对应的接口
  2. 询问用户补全所有缺失的必填参数
  3. 如果有存储的凭证则直接使用，否则询问用户获取
  4. 使用内置的
    scripts/sign_and_call.sh
    执行请求
  5. 以易读的格式展示响应结果
  6. 如果请求失败，展示错误信息并给出修复建议

Important Notes for Pre-order API

预下单API重要注意事项

Timestamp Generation (Cross-platform)

跨平台时间戳生成

When generating timestamps for the 
ts
parameter and 
externalOrderId
, use the following approach for cross-platform compatibility:
bash
undefined
为
ts
参数和
externalOrderId
生成时间戳时，请使用以下跨平台兼容的方案：
bash
undefined

Generate millisecond timestamp (works on macOS, Linux, BSD)

生成毫秒级时间戳（兼容macOS、Linux、BSD）

TIMESTAMP=$(($(date +%s) * 1000))
TIMESTAMP=$(($(date +%s) * 1000))

Generate unique order ID

生成唯一订单ID

ORDER_ID="order$(date +%s)"

**DO NOT USE** `date +%s%3N` or `date +%s000` as these are not portable:
- `date +%s%3N` doesn't work on macOS (outputs literal 'N')
- `date +%s000` just appends '000' without actual millisecond precision
ORDER_ID="order$(date +%s)"

**禁止使用** `date +%s%3N` 或 `date +%s000`，因为这两种写法不具备可移植性：
- `date +%s%3N` 在macOS上无法正常工作（会输出字面量'N'）
- `date +%s000` 只是简单拼接'000'，没有实际毫秒级精度

Order ID Format

订单ID格式

The 
externalOrderId
must be a valid string without special characters. Recommended formats:
  • order1773744500
    (simple numeric suffix)
  • order_1773744500
    (with underscore separator)
  • txn-abc123
    (custom prefix with alphanumeric)
Avoid: 
order_${TIMESTAMP}
where TIMESTAMP contains shell variable syntax errors
externalOrderId
必须是不含特殊字符的有效字符串，推荐格式：
  • order1773744500
    （简单数字后缀）
  • order_1773744500
    （带下划线分隔符）
  • txn-abc123
    （自定义前缀加字母数字组合）
避免使用：
order_${TIMESTAMP}
这类包含Shell变量语法错误的格式

Example Pre-order Request

预下单请求示例

bash
undefined
bash
undefined

Correct way to create a pre-order

创建预订单的正确方式

TIMESTAMP=$(($(date +%s) * 1000)) ORDER_ID="order$(date +%s)"
bash /path/to/scripts/sign_and_call.sh
"https://api.commonservice.io"
"papi/v1/ramp/connect/gray/buy/pre-order"
"connect-gray"
"your-api-key"
"/path/to/private.pem"
"{"externalOrderId":"$ORDER_ID","merchantCode":"connect-gray","merchantName":"YourMerchant","ts":$TIMESTAMP,"fiatCurrency":"USD","requestedAmount":100,"cryptoCurrency":"BNB","amountType":1,"address":"0x...","network":"BSC","payMethodCode":"BUY_CARD"}"
undefined
TIMESTAMP=$(($(date +%s) * 1000)) ORDER_ID="order$(date +%s)"
bash /path/to/scripts/sign_and_call.sh
"https://api.commonservice.io"
"papi/v1/ramp/connect/gray/buy/pre-order"
"connect-gray"
"your-api-key"
"/path/to/private.pem"
"{"externalOrderId":"$ORDER_ID","merchantCode":"connect-gray","merchantName":"YourMerchant","ts":$TIMESTAMP,"fiatCurrency":"USD","requestedAmount":100,"cryptoCurrency":"BNB","amountType":1,"address":"0x...","network":"BSC","payMethodCode":"BUY_CARD"}"
undefined