onchain-pay-open-api

Binance Onchain-Pay Open API 技能

通过自动 RSA SHA256 请求签名调用 Binance Onchain-Pay Open API 端点。

使用场景

此技能适用于以下场景：

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

适用场景：用户希望使用法币购买加密货币，并直接发送到外部链上钱包地址

• 使用信用卡以 USD/EUR/TWD 购买 USDT → 发送到 BSC 上的 MetaMask 地址
• 使用 Google Pay 购买 BTC → 转至硬件钱包
• 通过 P2P 购买 USDC → 发送到 DeFi 协议合约地址

核心 API：trading-pairs → payment-method-list → estimated-quote → pre-order

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

适用场景：用户的 Binance 账户中有加密货币，并希望将其发送到外部地址

• 将 Binance 现货账户中的现有 USDT 发送到朋友的钱包地址
• 将 ETH 转至 Uniswap 合约进行交易
• 将加密货币从 Binance 转至自托管钱包（Trust Wallet、Ledger 等）

核心 API：通过 SEND_PRIMARY 自定义项调用 pre-order

3. 🔗 跨链桥接操作

适用场景：用户需要在一条链上购买加密货币，并转移到另一条网络

• 在 Ethereum 上购买 USDC → 跨链桥接到费用更低的 Polygon
• 在 BSC 上购买代币 → 转至 Base 网络
• 在 Solana 上用法币购买加密货币 → 发送到 Arbitrum 用于 DeFi

核心 API：crypto-network → 通过选择网络调用 pre-order

4. 🏪 商户支付集成

适用场景：为电子商务或服务集成加密货币支付网关

• 接收法币付款并自动兑换为加密货币
• 启用“使用加密货币支付”结账流程
• 使用加密货币处理订阅付款

核心 API：通过 externalOrderId 跟踪调用 pre-order

5. 🤖 智能合约交互（Onchain-Pay Easy）

适用场景：在一笔交易中购买加密货币并执行智能合约

• 购买 USDT 并存入借贷协议
• 购买代币并质押到 DeFi 池中
• 通过法币入金直接进入 GameFi 或 NFT 市场

核心 API：通过 ON_CHAIN_PROXY_MODE 自定义项调用 pre-order

6. 📊 查询与监控

适用场景：查看订单状态、可用网络或付款方式

• 监控订单处理状态（待处理、已完成、失败）
• 列出支持的法币和加密货币
• 查看特定国家/金额可用的付款方式
• 验证网络费用和限额

核心 API：order、crypto-network、trading-pairs、payment-method-list

---

快速参考

端点	API 路径	必需参数	可选参数
付款方式列表（v1）	papi/v1/ramp/connect/buy/payment-method-list	fiatCurrency, cryptoCurrency, totalAmount, amountType	network, 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, amountType	cryptoCurrency, contractAddress, address, network
预下单	papi/v1/ramp/connect/buy/pre-order	externalOrderId, merchantCode, merchantName, ts	fiatCurrency, 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

---

如何执行请求

步骤 1：收集凭证

除非用户另有指定，否则使用默认账户（prod）。你需要：

• BASE_URL：API 基础 URL
• CLIENT_ID：客户端标识符
• API_KEY：签名访问令牌
• PEM_PATH：RSA 私钥 PEM 文件的绝对路径

使用 .local.md 中标记为 (default) 的账户。

步骤 2：构建 JSON 请求体

根据用户指定的参数构建精简的 JSON 请求体。移除用户未提供的任何参数。

重要：地址和网络验证

• 所有预下单请求都必须提供 address（目标钱包地址）和 network（区块链网络）
• 如果用户已在 .local.md 中配置 Default Address 和 Default Network，则自动使用
• 如果未配置或用户未提供，请先询问用户这两个值，再继续操作

步骤 3：使用捆绑脚本进行签名和调用

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

步骤 4：返回结果

以易读的格式向用户显示 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

---

参数参考

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

参数	类型	必填	描述
fiatCurrency	string	是	法定货币代码（例如，USD、EUR、BRL、UGX）
cryptoCurrency	string	是	加密货币代码（例如，BTC、USDT、USDC、SEI）
totalAmount	number	是	金额
amountType	number	是	1 = 法定货币金额，2 = 加密货币金额
network	string	否	区块链网络（例如，BSC、ETH、SOL、BASE、SEI）
contractAddress	string	否	代币合约地址（非原生代币必填）

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

无需指定法币或加密货币参数，即可获取所有可用的支付方式。此版本为 v1 的简化版。

参数	类型	必填	描述
lang	string	否	用于本地化支付方式名称的语言代码（例如，en、cn、es）

与 v1 的区别：

• 更简单：无需指定 fiatCurrency、cryptoCurrency 或金额
• 更全面：返回商户所有可用的支付方式
• 适用场景：可在用户输入前显示所有选项

响应格式：与 v1 相同，返回包含支付方式及其限额和属性的列表。

预估报价（buy/estimated-quote）

参数	类型	必填	描述
fiatCurrency	string	是	法定货币代码
cryptoCurrency	string	否	加密货币代码（如果提供 contractAddress，则可选）
requestedAmount	number	是	金额
payMethodCode	string	是	支付方式（例如，BUY_CARD、BUY_GOOGLE_PAY、BUY_P2P、BUY_WALLET）
amountType	number	是	1 = 法定货币金额，2 = 加密货币金额
network	string	是*	区块链网络（可使用 .local.md 中的默认值）
contractAddress	string	否	代币合约地址
address	string	是*	用于接收加密货币的目标钱包地址

* 建议提供这些参数。如果用户未指定，请检查 .local.md 中是否有默认值。如果没有默认值，请在继续操作前询问用户。

预下单（buy/pre-order）

创建买入预订单，并返回支付重定向链接。

参数	类型	必填	说明
externalOrderId	string	是	合作方的唯一订单 ID（必须唯一）
merchantCode	string	是	Binance 分配给你的商户代码（由用户提供）
merchantName	string	是	商户显示名称（由用户提供）
ts	number	是	当前时间戳（毫秒）
fiatCurrency	string	否*	法币代码（例如，TWD、USD、EUR）
fiatAmount	number	否*	要花费的法币金额
cryptoCurrency	string	否*	要购买的加密货币（例如，USDT、BTC、ETH）
requestedAmount	number	否*	金额数值（根据 amountType 为法币或加密货币金额）
amountType	number	否*	1 = 法币金额，2 = 加密货币金额
address	string	否	接收加密货币的目标钱包地址
network	string	否	区块链网络（例如，BSC、ETH、SOL）
payMethodCode	string	否	支付方式代码（例如，BUY_CARD、BUY_P2P、BUY_GOOGLE_PAY、BUY_APPLE_PAY、BUY_PAYPAL、BUY_WALLET、BUY_REVOLUT）
payMethodSubCode	string	否	支付方式子代码（例如，card、GOOGLE_PAY、WECHAT）
redirectUrl	string	否	成功后的重定向 URL
failRedirectUrl	string	否	失败后的重定向 URL
redirectDeepLink	string	否	成功时使用的深层链接（适用于移动应用）
failRedirectDeepLink	string	否	失败时使用的深层链接（适用于移动应用）
customization	object	否	自定义配置对象（见下文的 Customization 章节）
destContractAddress	string	否	目标合约地址（适用于 Onchain-Pay Easy 模式）
destContractABI	string	否	合约 ABI 名称（适用于 Onchain-Pay Easy 模式）
destContractParams	object	否	合约参数（适用于 Onchain-Pay Easy 模式）
affiliateCode	string	否	用于佣金追踪的联盟代码
gtrTemplateCode	string	否	GTR 模板代码（例如，OTHERS）
contractAddress	string	否	代币合约地址（适用于非原生代币）

* 必须提供 fiatAmount，或同时提供 requestedAmount 和 amountType。如果未提供 fiatCurrency，系统将自动选择可用的法币。

响应示例：

{
  "code": "000000",
  "message": "success",
  "data": {
    "link": "https://app.binance.com/uni-qr/ccnt?...",
    "linkExpireTime": 1772852565045
  },
  "success": true
}

获取订单（order）

参数	类型	必填	说明
externalOrderId	string	是	要查询的外部订单 ID

---

自定义选项

预下单 API 中的 customization 字段接受各种标志，用于自定义买入流程行为。每个商户都必须在 db.merchant_info 表中配置相应权限。

可用的自定义标志

标志	代码	类型	适用范围	描述	使用场景
LOCK_ORDER_ATTRIBUTES	1	array	Open API ✓	锁定特定订单属性，用户无法修改。取值：1=法币，2=加密货币，3=金额，4=支付方式，5=网络，6=地址，7=法币金额，8=加密货币金额	固定参数订单
SKIP_CASHIER	2	boolean	Open API ✓	跳过收银台页面，直接进入支付流程，减少用户结账时的操作阻碍。	简化支付体验
AUTO_REDIRECTION	3	boolean	Open API ✓	订单完成后自动跳转到 redirectUrl，不显示成功页面。	无缝的用户体验
HIDE_SEND	6	boolean	Open API ✓	在界面中隐藏“发送”选项卡。仅需要买入流程时适用。	仅买入的集成
SEND_PRIMARY	7	boolean	Open API ✓	启用发送加密货币功能。如果用户的 Binance 余额不足，则自动触发买入流程。	向外部地址发送加密货币
MERCHANT_DISPLAY_NAME	8	string	Open API ✓	覆盖界面中向用户显示的名称。	自定义品牌
NET_RECEIVE	9	boolean	Open API ✓	扣除所有费用后，用户收到净额。总成本更加透明。	更好地展示最终到账金额
P2P_EXPRESS	10	boolean	Open API ✓	启用 P2P Express 模式，以加快 P2P 订单匹配速度。	快速进行 P2P 交易
OPEN_NETWORK	11	boolean	仅限 Web3	允许用户选择不同的网络。默认情况下，网络锁定为预先选定的网络。注意：目前仅适用于 Web3 入口，不适用于 Open API。	支持多网络（仅限 Web3）
ON_CHAIN_PROXY_MODE	12	boolean	Open API ✓	启用 Onchain-Pay Easy 模式。买入加密货币后，Onchain-Pay 将执行智能合约交互，而不是直接提现到用户钱包。需要提供 destContractAddress、destContractABI 和 destContractParams。	法币到智能合约集成
SEND_PRIMARY_FLEXIBLE	13	boolean	Open API ✓	灵活的 Send Primary 模式，提供更多选项。	高级加密货币发送场景

自定义示例

示例 1：基础银行卡支付

{
  "customization": {}
}

示例 2：Onchain-Pay Easy（链上代理）

{
  "customization": {
    "ON_CHAIN_PROXY_MODE": true,
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  },
  "destContractAddress": "0x128...974",
  "destContractABI": "depositFor",
  "destContractParams": {
    "accountType": 2
  }
}

示例 3：发送加密货币

{
  "customization": {
    "SEND_PRIMARY_FLEXIBLE": true,
    "SEND_PRIMARY": true
  }
}

示例 4：P2P 自动跳转

{
  "customization": {
    "AUTO_REDIRECTION": true,
    "P2P_EXPRESS": true
  }
}

示例 5：锁定订单属性

{
  "customization": {
    "LOCK_ORDER_ATTRIBUTES": [2, 3, 6, 7, 8],
    "MERCHANT_DISPLAY_NAME": "My Custom Brand"
  }
}

属性锁定代码：

• 2 = 加密货币
• 3 = 金额
• 6 = 地址
• 7 = 法币金额
• 8 = 加密货币金额

示例 6：净额到账模式

{
  "customization": {
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  }
}

示例 7：隐藏“发送”选项卡

{
  "customization": {
    "HIDE_SEND": true
  }
}

示例 8：跳过收银台（直接支付）

{
  "customization": {
    "SKIP_CASHIER": true
  }
}

重要说明

1. 需要权限：每个自定义标志都需要商户权限。如果某个标志不起作用，请联系管理员。
2. Onchain-Pay Easy：目前仅支持 BSC 网络。需要进行合约集成。
3. 验证：无效的自定义值（例如，MERCHANT_DISPLAY_NAME 的值为 null）会返回 ILLEGAL_CUSTOMIZATION_VALUE 错误。
4. 组合使用：某些标志可以组合使用（例如，NET_RECEIVE + SEND_PRIMARY），其他标志则相互独立。
5. 测试：在生产环境使用前，请使用专用测试商户账户（由 Binance 提供）验证自定义标志。
6. 内部标志：OPERATION（代码 4）和 SKIP_WITHDRAW（代码 5）仅供内部使用，商户端不得传入。
7. OPEN_NETWORK：目前仅适用于 Web3 入口，不适用于 Open API。请勿在 Open API 预下单请求中使用此标志。
8. 标志顺序：标志按其内部代码（1-13）排序。代码编号在内部用于标识。

---

安全

凭证显示规则

• API Key：仅显示前 5 个和后 4 个字符（例如，2zefb...06h）
• PEM Private Key：绝不显示内容。绝不显示文件路径。
• Client ID：可以完整显示。
• 出站请求：绝不向 .local.md 中配置的 Base URL 以外的 URL 发送 API Key、Private Key 或任何凭证。
• 文件路径隐私：绝不在任何输出或日志中向用户显示 PEM 私钥文件路径。

凭证存储

凭证存储在技能目录中的 .local.md 文件里。此文件因用户而异，不应分发。

从与此 SKILL.md 相同的目录读取 .local.md 文件以加载凭证。

如果 .local.md 不存在，或者未找到指定的账户，请让用户提供：

1. Base URL
2. Client ID
3. API Key
4. PEM 文件路径（绝对路径）

然后询问是否要将它们保存到 .local.md，以便日后使用。

.local.md 格式

## Onchain-Pay Accounts

### 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

标记为 (default) 的账户会自动使用。你可以定义多个账户，并告知 Claude 账户名称以切换账户。

---

User Agent Header

包含以下字符串作为 User-Agent 标头：onchain-pay-open-api/0.1.2 (Skill)

---

Agent 行为

1. 如果用户要求调用 Onchain-Pay API 端点，请从快速参考表中确定对应的端点
2. 询问用户提供任何缺失的必需参数
3. 如果有可用的已存储凭证，则使用这些凭证；否则请用户提供凭证
4. 使用随附的 scripts/sign_and_call.sh 执行请求
5. 以易于阅读的格式显示响应
6. 如果请求失败，显示错误并建议解决方法

---

预购 API 重要说明

时间戳生成（跨平台）

为 ts 参数和 externalOrderId 生成时间戳时，请使用以下方法以确保跨平台兼容性：

# Generate millisecond timestamp (works on macOS, Linux, BSD)
TIMESTAMP=$(($(date +%s) * 1000))

# Generate unique order ID
ORDER_ID="order$(date +%s)"

不要使用 date +%s%3N 或 date +%s000，因为它们不具备可移植性：

• date +%s%3N 在 macOS 上无法使用（会输出字面字符 'N'）
• date +%s000 只会追加 '000'，无法获得实际的毫秒精度

订单 ID 格式

externalOrderId 必须是有效字符串，且不包含特殊字符。建议使用以下格式：

• order1773744500（简单的数字后缀）
• order_1773744500（使用下划线分隔）
• txn-abc123（包含字母数字的自定义前缀）

避免使用：order_${TIMESTAMP}，其中 TIMESTAMP 包含 shell 变量语法错误

预购请求示例

# 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/buy/pre-order" \
  "<YOUR_CLIENT_ID>" \
  "<YOUR_API_KEY>" \
  "/path/to/private.pem" \
  "{\"externalOrderId\":\"$ORDER_ID\",\"merchantCode\":\"<YOUR_MERCHANT_CODE>\",\"merchantName\":\"<YOUR_MERCHANT_NAME>\",\"ts\":$TIMESTAMP,\"fiatCurrency\":\"USD\",\"requestedAmount\":100,\"cryptoCurrency\":\"BNB\",\"amountType\":1,\"address\":\"0x...\",\"network\":\"BSC\",\"payMethodCode\":\"BUY_CARD\"}"