onchain-pay-open-api

Files (7)

• .gitignore
• .local.md.example
• CHANGELOG.md
• LICENSE.md
• SKILL.md
• authentication.md · references/
• sign_and_call.sh · scripts/

SKILL.md (first lines)

# 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/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
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`](./references/authentication.md) for full signing details.

Summary:

From binance/binance-skills-hub, MIT.

More from binance/binance-skills-hub