onchain-pay-open-api

What this skill does

# 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
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:
1. Payload = `JSON_BODY` + `TIMESTAMP` (milliseconds)
2. Sign payload with RSA SHA256 using PEM private key
3. Base64 encode the signature (single line)
4. 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`) |
| m