Binance Onchain-Pay Open API 技能 (Binance Onchain-Pay Open API Skill)

调用币安 Onchain-Pay Open API 端点，并使用 RSA SHA256 自动进行请求签名。

用例与场景 (Use Cases & Scenarios)

此技能专为以下场景设计：

1. 💳 法币购买加密货币并发送 (Fiat-to-Crypto Purchase & Send)

何时使用 (When to use)：用户想用法币购买加密货币并直接发送到外部链上钱包地址

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

关键 API (Key APIs)：trading-pairs → payment-method-list → estimated-quote → pre-order

2. 🔄 直接加密货币转账（发送为主）(Direct Crypto Transfer – Send Primary)

何时使用 (When to use)：用户在币安账户中有加密货币，想要发送到外部地址

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

关键 API (Key APIs)：带有 SEND_PRIMARY 自定义配置的 pre-order

3. 🔗 跨链桥接操作 (Cross-Chain Bridge Operations)

何时使用 (When to use)：用户需要在一条链上购买加密货币并转移到另一条网络

• 在以太坊上购买 USDC → 桥接到 Polygon 以降低费用
• 在 BSC 上购买代币 → 转移到 Base 网络
• 在 Solana 上用法币购买 → 发送到 Arbitrum 进行 DeFi 操作

关键 API (Key APIs)：crypto-network → 带网络选择的 pre-order

4. 🏪 商家支付集成 (Merchant Payment Integration)

何时使用 (When to use)：为电子商务或服务集成加密货币支付网关

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

关键 API (Key APIs)：带有 externalOrderId 跟踪的 pre-order

5. 🤖 智能合约交互（Onchain-Pay Easy）(Smart Contract Interaction – Onchain-Pay Easy)

何时使用 (When to use)：在一笔交易中购买加密货币并执行智能合约

• 购买 USDT 并存入借贷协议
• 购买代币并在 DeFi 池中质押
• 法币入口直接连接到 GameFi 或 NFT 市场

关键 API (Key APIs)：带有 ON_CHAIN_PROXY_MODE 自定义配置的 pre-order

6. 📊 查询与监控 (Query & Monitoring)

何时使用 (When to use)：检查订单状态、可用网络或支付方式

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

关键 API (Key APIs)：order、crypto-network、trading-pairs、payment-method-list

快速参考 (Quick Reference)

如何执行请求 (How to Execute a Request)

步骤 1：收集凭证 (Step 1: Gather credentials)

除非用户另有指定，否则使用默认账户（生产环境）。您需要：

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

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

步骤 2：构建 JSON 请求体 (Step 2: Build the JSON body)

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

重要：地址和网络验证 (IMPORTANT: Address and Network Validation)

• address（目标钱包地址）和 network（区块链网络）是所有预下单请求的必需项
• 如果用户在 .local.md 中配置了 Default Address 和 Default Network，则自动使用它们
• 如果未配置或用户未提供，在继续之前询问用户提供这两个值

步骤 3：使用捆绑脚本签名并调用 (Step 3: Sign and call using the bundled script)

bash <技能路径 (skill_path)>/scripts/sign_and_call.sh \
  "<BASE_URL>" \
  "<API_PATH>" \
  "<CLIENT_ID>" \
  "<API_KEY>" \
  "<PEM_PATH>" \
  '<JSON_BODY>'

步骤 4：返回结果 (Step 4: Return results)

以可读格式向用户显示 JSON 响应。

认证 (Authentication)

有关完整签名详情，请参阅 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)

支付方式列表 v1 (buy/payment-method-list)

支付方式列表 v2 (v2/buy/payment-method-list)

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

与 v1 的区别 (Differences from v1)：

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

响应格式 (Response Format)：与 v1 相同，返回带有其限额和属性的支付方式列表。

预估报价 (buy/estimated-quote)

* 建议提供这些参数。如果用户未指定，请检查 .local.md 中的默认值。如果不存在默认值，请在继续之前询问用户。

预下单 (buy/pre-order)

创建购买预下单并返回支付重定向链接。

* 应提供 fiatAmount 或（requestedAmount + amountType）。如果未提供 fiatCurrency，系统将自动选择可用的法币。

响应示例 (Response Example)：

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

获取订单 (order)

自定义选项 (Customization Options)

预下单 API 中的 customization 字段接受各种标志来定制购买流程行为。每个商户必须在 db.merchant_info 表中配置相应的权限。

可用自定义标志 (Available Customization Flags)

自定义示例 (Customization Examples)

示例 1：基础银行卡支付 (Basic Card Payment)

{
  "customization": {}
}

示例 2：Onchain-Pay Easy（链上代理）(Onchain-Pay Easy – On-Chain Proxy)

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

示例 3：发送加密货币 (Send Crypto)

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

示例 4：带自动重定向的 P2P (P2P with Auto Redirection)

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

示例 5：锁定订单属性 (Lock Order Attributes)

{
  "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)

示例 6：净额接收模式 (Net Receive Mode)

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

示例 7：隐藏发送选项卡 (Hide Send Tab)

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

示例 8：跳过收银台（直接支付）(Skip Cashier – Direct Payment)

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

重要说明 (Important Notes)

1. 需要权限 (Permission Required)：每个自定义标志都需要商户权限。如果标志不起作用，请咨询管理员。
2. Onchain-Pay Easy：目前仅支持 BSC 网络。需要合约集成。
3. 验证 (Validation)：无效的自定义值（例如 MERCHANT_DISPLAY_NAME 为 null）将返回 ILLEGAL_CUSTOMIZATION_VALUE 错误。
4. 组合 (Combinations)：某些标志可以一起使用（例如 NET_RECEIVE + SEND_PRIMARY），而其他标志则是独立的。
5. 测试 (Testing)：在生产环境之前，使用测试账户（connect-gray）测试自定义标志。
6. 内部标志 (Internal Flags)：OPERATION（代码 4）和 SKIP_WITHDRAW（代码 5）仅供内部使用，不应从商户端传递。
7. OPEN_NETWORK：目前仅适用于 Web3 入口，不适用于 Open API。请勿在 Open API 预下单请求中使用此标志。
8. 标志顺序 (Flag Order)：标志按其内部代码（1-13）排序。代码编号用于内部识别。

安全 (Security)

凭证显示规则 (Credential Display Rules)

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

凭证存储 (Credential Storage)

凭证存储在技能目录中的 .local.md 文件中。此文件是 用户特定的 (user-specific)，不应分发。

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

如果 .local.md 不存在或未找到请求的账户，请要求用户提供：

1. Base URL
2. Client ID
3. API Key
4. PEM 文件路径（绝对路径）(PEM file path – absolute path)

然后提供将其保存到 .local.md 以供将来使用的选项。

.local.md 格式 (Format)

## Onchain-Pay 账户 (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.0 (Skill)

智能体行为 (Agent Behavior)

1. 如果用户要求调用 Onchain-Pay API 端点，从快速参考表中识别端点
2. 询问任何缺失的必需参数
3. 如果可用，使用存储的凭证，否则询问用户
4. 使用捆绑的 scripts/sign_and_call.sh 执行请求
5. 以可读格式显示响应
6. 如果请求失败，显示错误并提出修复建议

预下单 API 的重要说明 (Important Notes for Pre-order API)

时间戳生成（跨平台）(Timestamp Generation – Cross-platform)

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

# 生成毫秒时间戳 (适用于 macOS、Linux、BSD) (Generate millisecond timestamp - works on macOS, Linux, BSD)
TIMESTAMP=$(($(date +%s) * 1000))

# 生成唯一订单 ID (Generate unique order ID)
ORDER_ID="order$(date +%s)"

不要使用 (DO NOT USE) date +%s%3N 或 date +%s000，因为它们不可移植：

• date +%s%3N 在 macOS 上不起作用（输出字面 ‘N’）
• date +%s000 只是附加 ‘000’，没有实际的毫秒精度

订单 ID 格式 (Order ID Format)

externalOrderId 必须是有效字符串，不含特殊字符。推荐格式：

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

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

预下单请求示例 (Example Pre-order Request)

# 正确创建预下单的方式 (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\"}"