onchain-pay-open-api

仓库: binance/binance-skills-hub
安装量: 141
排名: #6059

安装

npx skills add https://github.com/binance/binance-skills-hub --skill onchain-pay-open-api
Binance Onchain-Pay Open API Skill
Call Binance Onchain-Pay Open API endpoints with automatic RSA SHA256 request signing.
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.
Step 3: Sign and call using the bundled script
bash
<
skill_path
>
/scripts/sign_and_call.sh
\
""
\
""
\
""
\
""
\
""
\
''
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
No
Blockchain network
contractAddress
string
No
Token contract address
address
string
No
Destination wallet address
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
,
"P2P_EXPRESS"
:
true
}
}
Example 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
Example 6: Net Receive Mode
{
"customization"
:
{
"NET_RECEIVE"
:
true
,
"SEND_PRIMARY"
:
true
}
}
Example 7: Hide Send Tab
{
"customization"
:
{
"HIDE_SEND"
:
true
}
}
Example 8: Skip Cashier (Direct Payment)
{
"customization"
:
{
"SKIP_CASHIER"
:
true
}
}
Important Notes
Permission Required
Each customization flag requires merchant permission. Check with admin if a flag is not working.
Onchain-Pay Easy
Only supported on BSC network currently. Requires contract integration.
Validation
Invalid customization values (e.g.,
null
for
MERCHANT_DISPLAY_NAME
) will return
ILLEGAL_CUSTOMIZATION_VALUE
error.
Combinations
Some flags work together (e.g.,
NET_RECEIVE
+
SEND_PRIMARY
), while others are independent.
Testing
Use test accounts (
connect-gray
) for testing customization flags before production.
Internal Flags
:
OPERATION
(code 4) and
SKIP_WITHDRAW
(code 5) are internal use only and should NOT be passed from merchant side.
OPEN_NETWORK
Currently only available for Web3 entrance, not available for Open API. Do not use this flag in Open API pre-order requests.
Flag Order
Flags are ordered by their internal code (1-13). The code number is used internally for identification.
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. 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: Base URL Client ID API Key PEM file path (absolute path) Then offer to save them to .local.md for future use. .local.md Format

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

Description: Production account The account marked (default) is used automatically. You can define multiple accounts and switch by telling Claude the account name. User Agent Header Include User-Agent header with the following string: onchain-pay-open-api/0.1.0 (Skill) Agent Behavior If the user asks to call an Onchain-Pay API endpoint, identify which endpoint from the Quick Reference table Ask for any missing required parameters Use stored credentials if available, otherwise ask the user Execute the request using the bundled scripts/sign_and_call.sh Display the response in a readable format If the request fails, show the error and suggest fixes

← 返回排行榜