Binance Onchain-Pay Open API Skill
Call Binance Onchain-Pay Open API endpoints with automatic RSA SHA256 request signing.
Use Cases & Scenarios
This skill is designed for the following scenarios:
1. 💳 Fiat-to-Crypto Purchase & Send
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
2. 🔄 Direct Crypto Transfer (Send Primary)
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
3. 🔗 Cross-Chain Bridge Operations
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
4. 🏪 Merchant Payment Integration
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
5. 🤖 Smart Contract Interaction (Onchain-Pay Easy)
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
6. 📊 Query & Monitoring
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
Quick Reference
| Endpoint |
API Path |
Required Params |
Optional Params |
| Payment Method List (v1) |
papi/v1/ramp/connect/buy/payment-method-list |
fiatCurrency, cryptoCurrency, totalAmount, amountType |
network, 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, amountType |
cryptoCurrency, contractAddress, address, network |
| Pre-order |
papi/v1/ramp/connect/gray/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 |
| 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 |
How to Execute a Request
Step 1: Gather credentials
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.
Step 2: Build the JSON body
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
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>'
Step 4: Return results
Display the JSON response to the user in a readable format.
Authentication
See references/authentication.md for full signing details.
Summary:
- Payload =
JSON_BODY + TIMESTAMP (milliseconds)
- Sign payload with RSA SHA256 using PEM private key
- Base64 encode the signature (single line)
- Send as POST with headers:
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)
| Parameter |
Type |
Required |
Description |
| fiatCurrency |
string |
Yes |
Fiat currency code (e.g., USD, EUR, BRL, UGX) |
| cryptoCurrency |
string |
Yes |
Crypto currency code (e.g., BTC, USDT, USDC, SEI) |
| totalAmount |
number |
Yes |
Amount value |
| amountType |
number |
Yes |
1 = fiat amount, 2 = crypto amount |
| network |
string |
No |
Blockchain network (e.g., BSC, ETH, SOL, BASE, SEI) |
| contractAddress |
string |
No |
Token contract address (required for non-native tokens) |
Payment Method List v2 (v2/buy/payment-method-list)
Get all available payment methods without specifying fiat/crypto parameters. Simplified version of v1.
| Parameter |
Type |
Required |
Description |
| lang |
string |
No |
Language 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.
Estimated Quote (buy/estimated-quote)
| Parameter |
Type |
Required |
Description |
| fiatCurrency |
string |
Yes |
Fiat currency code |
| cryptoCurrency |
string |
No |
Crypto currency code (optional if contractAddress provided) |
| requestedAmount |
number |
Yes |
Amount value |
| payMethodCode |
string |
Yes |
Payment method (e.g., BUY_CARD, BUY_GOOGLE_PAY, BUY_P2P, BUY_WALLET) |
| amountType |
number |
Yes |
1 = fiat amount, 2 = crypto amount |
| network |
string |
Yes* |
Blockchain network (can use default from .local.md) |
| contractAddress |
string |
No |
Token contract address |
| address |
string |
Yes* |
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.
Pre-order (buy/pre-order)
Create a buy pre-order and return the redirect link for payment.
| Parameter |
Type |
Required |
Description |
| externalOrderId |
string |
Yes |
Partner's unique order ID (must be unique) |
| merchantCode |
string |
Yes |
Merchant code (e.g., connect-gray) |
| merchantName |
string |
Yes |
Merchant display name (e.g., GrayTest) |
| ts |
number |
Yes |
Current timestamp in milliseconds |
| fiatCurrency |
string |
No* |
Fiat currency code (e.g., TWD, USD, EUR) |
| fiatAmount |
number |
No* |
Fiat amount to spend |
| cryptoCurrency |
string |
No* |
Crypto currency to buy (e.g., USDT, BTC, ETH) |
| requestedAmount |
number |
No* |
Amount value (fiat or crypto based on amountType) |
| amountType |
number |
No* |
1 = fiat amount, 2 = crypto amount |
| address |
string |
No |
Destination wallet address for receiving crypto |
| network |
string |
No |
Blockchain network (e.g., BSC, ETH, SOL) |
| payMethodCode |
string |
No |
Payment method code (e.g., BUY_CARD, BUY_P2P, BUY_GOOGLE_PAY, BUY_APPLE_PAY, BUY_PAYPAL, BUY_WALLET, BUY_REVOLUT) |
| payMethodSubCode |
string |
No |
Payment method sub-code (e.g., card, GOOGLE_PAY, WECHAT) |
| redirectUrl |
string |
No |
Success redirect URL |
| failRedirectUrl |
string |
No |
Failure redirect URL |
| redirectDeepLink |
string |
No |
Deep link for success (mobile apps) |
| failRedirectDeepLink |
string |
No |
Deep link for failure (mobile apps) |
| customization |
object |
No |
Custom configuration object (see Customization section below) |
| destContractAddress |
string |
No |
Destination contract address (for Onchain-Pay Easy mode) |
| destContractABI |
string |
No |
Contract ABI name (for Onchain-Pay Easy mode) |
| destContractParams |
object |
No |
Contract parameters (for Onchain-Pay Easy mode) |
| affiliateCode |
string |
No |
Affiliate code for commission tracking |
| gtrTemplateCode |
string |
No |
GTR template code (e.g., OTHERS) |
| contractAddress |
string |
No |
Token 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:
{
"code": "000000",
"message": "success",
"data": {
"link": "https://app.binance.com/uni-qr/ccnt?...",
"linkExpireTime": 1772852565045
},
"success": true
}
Get Order (order)
| Parameter |
Type |
Required |
Description |
| externalOrderId |
string |
Yes |
The external order ID to query |
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.
Available Customization Flags
| Flag |
Code |
Type |
Availability |
Description |
Use Case |
LOCK_ORDER_ATTRIBUTES |
1 |
array |
Open 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 |
2 |
boolean |
Open API ✓ |
Skip the cashier page and proceed directly to payment. Reduces user friction in the checkout flow. |
Streamlined payment experience |
AUTO_REDIRECTION |
3 |
boolean |
Open API ✓ |
Automatically redirect to redirectUrl after order completion without showing success page. |
Seamless user experience |
HIDE_SEND |
6 |
boolean |
Open API ✓ |
Hide the "Send" tab in the UI. Useful when only buy flow is needed. |
Buy-only integration |
SEND_PRIMARY |
7 |
boolean |
Open 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 |
8 |
string |
Open API ✓ |
Override the display name shown to users in the UI. |
Custom branding |
NET_RECEIVE |
9 |
boolean |
Open API ✓ |
User receives net amount after deducting all fees. Total cost is more transparent. |
Better UX for showing final received amount |
P2P_EXPRESS |
10 |
boolean |
Open API ✓ |
Enable P2P Express mode for faster P2P order matching. |
Quick P2P transactions |
OPEN_NETWORK |
11 |
boolean |
Web3 only |
Allow 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 |
12 |
boolean |
Open 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 |
13 |
boolean |
Open API ✓ |
Flexible Send Primary mode with more options. |
Advanced send crypto scenarios |
Customization Examples
Example 1: Basic Card Payment
{
"customization": {}
}
Example 2: 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
}
}
Example 3: Send Crypto
{
"customization": {
"SEND_PRIMARY_FLEXIBLE": true,
"SEND_PRIMARY": true
}
}
Example 4: P2P with Auto Redirection
{
"customization": {
"AUTO_REDIRECTION": true,
