Create sponsored transfer (quote)

curl --request POST \
  --url https://api.platform.bitnob.com/sponsored-transfers \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": "10.50",
  "asset": "USDC",
  "chain": "solana",
  "from": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2",
  "to": "3xTd...recipient",
  "network": "mainnet",
  "router_version": 2,
  "treat_as_gross_amount": true
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '10.50',
    asset: 'USDC',
    chain: 'solana',
    from: '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2',
    to: '3xTd...recipient',
    network: 'mainnet',
    router_version: 2,
    treat_as_gross_amount: true
  })
};

fetch('https://api.platform.bitnob.com/sponsored-transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.platform.bitnob.com/sponsored-transfers"

payload = {
    "amount": "10.50",
    "asset": "USDC",
    "chain": "solana",
    "from": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2",
    "to": "3xTd...recipient",
    "network": "mainnet",
    "router_version": 2,
    "treat_as_gross_amount": True
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.platform.bitnob.com/sponsored-transfers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '10.50',
    'asset' => 'USDC',
    'chain' => 'solana',
    'from' => '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2',
    'to' => '3xTd...recipient',
    'network' => 'mainnet',
    'router_version' => 2,
    'treat_as_gross_amount' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.platform.bitnob.com/sponsored-transfers"

	payload := strings.NewReader("{\n  \"amount\": \"10.50\",\n  \"asset\": \"USDC\",\n  \"chain\": \"solana\",\n  \"from\": \"7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2\",\n  \"to\": \"3xTd...recipient\",\n  \"network\": \"mainnet\",\n  \"router_version\": 2,\n  \"treat_as_gross_amount\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.platform.bitnob.com/sponsored-transfers")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"10.50\",\n  \"asset\": \"USDC\",\n  \"chain\": \"solana\",\n  \"from\": \"7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2\",\n  \"to\": \"3xTd...recipient\",\n  \"network\": \"mainnet\",\n  \"router_version\": 2,\n  \"treat_as_gross_amount\": true\n}")
  .asString();

{
  "fee": {
    "amount": "0.02",
    "asset": "USDC",
    "usd": "0.02"
  },
  "object": "sponsored_transfer",
  "partner_fee": {
    "address": "9xQe...partner",
    "amount": "0.20",
    "asset": "USDC",
    "usd": "0.20"
  },
  "recipient_amount": "10.50",
  "sign": {
    "scheme": "solana_ed25519"
  },
  "status": "quoted",
  "total_debit": "10.72"
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

Create sponsored transfer (quote)

Quotes a gas-sponsored transfer for an external end-user (someone who holds their own key and has no Bitnob wallet) and returns the exact payload they must sign. Bitnob pays the network gas and recoups it as a fee in the transferred token, so neither party needs to hold the native gas asset (SOL, ETH, or TRX).

Amounts. amount is a decimal string in the asset’s normal units (for example "10.50" USDC). By default (net mode) amount is what the recipient receives and the sender (from) is debited total_debit, which is recipient_amount plus fee (the sponsorship fee) plus partner_fee (your optional markup). Set treat_as_gross_amount: true for gross mode: amount becomes the sender’s total debit (total_debit equals amount) and the sponsorship and partner fees are deducted from it, so recipient_amount is amount minus those fees. Gross mode lets you sweep a full source balance without overdrawing it; the request is rejected (invalid_request) when amount does not exceed the fees. The response echoes treat_as_gross_amount and both recipient_amount and total_debit so you can confirm the split.

Flow. First call create (this endpoint) to get a sign block and an expires_at. Then have the end-user sign it verbatim with their own key. Then submit the signature or signatures to POST /sponsored-transfers/{id}/submit. Finally poll GET /sponsored-transfers/{id} (or subscribe to sponsored_transfer.* webhooks) until the status is terminal. Sign and submit before expires_at.

What to sign depends on sign.scheme:

solana_ed25519: sign the raw message bytes in sign.message_base64 with the from ed25519 key, then submit the base58 signature as signature.
evm_7702: sign both the EIP-7702 authorization (sign.authorization) and the EIP-712 witness (sign.witness) with the from key, then submit both as 0x-prefixed 65-byte signatures. sign.digests gives the raw 32-byte hashes if you use a non-standard signer.
tron_router: sign the 0x-prefixed 32-byte digest in sign.digest with the from secp256k1 key and submit it as tron_signature. Important: on a sender’s first sponsored transfer of a given token, the quote also returns a sign.approve block with sign.approve.needed set to true. When that block is present you must ALSO sign sign.approve.digest with the same from key and submit it as tron_approve_signature in the same submit call, alongside tron_signature. This one-time approval is what lets the router pull the tokens on the sender’s behalf, and the transfer cannot be broadcast without it. It is needed only on the first transfer (later transfers do not return the block and need only tron_signature), the single quoted fee already covers its cost, and Bitnob activates the sender’s account first if it is brand new.

Partner markup (optional). Include partner_fee to charge your own flat fee (in the same asset) to an address you control, on top of the sponsorship fee. address and amount are required together, the address must not equal the sender or recipient, and the amount is capped per chain. Supported on Solana, EVM, and Tron. Requires the Idempotency-Key header.

POST

sponsored-transfers

Create sponsored transfer (quote)

curl --request POST \
  --url https://api.platform.bitnob.com/sponsored-transfers \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": "10.50",
  "asset": "USDC",
  "chain": "solana",
  "from": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2",
  "to": "3xTd...recipient",
  "network": "mainnet",
  "router_version": 2,
  "treat_as_gross_amount": true
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '10.50',
    asset: 'USDC',
    chain: 'solana',
    from: '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2',
    to: '3xTd...recipient',
    network: 'mainnet',
    router_version: 2,
    treat_as_gross_amount: true
  })
};

fetch('https://api.platform.bitnob.com/sponsored-transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.platform.bitnob.com/sponsored-transfers"

payload = {
    "amount": "10.50",
    "asset": "USDC",
    "chain": "solana",
    "from": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2",
    "to": "3xTd...recipient",
    "network": "mainnet",
    "router_version": 2,
    "treat_as_gross_amount": True
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.platform.bitnob.com/sponsored-transfers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '10.50',
    'asset' => 'USDC',
    'chain' => 'solana',
    'from' => '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2',
    'to' => '3xTd...recipient',
    'network' => 'mainnet',
    'router_version' => 2,
    'treat_as_gross_amount' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.platform.bitnob.com/sponsored-transfers"

	payload := strings.NewReader("{\n  \"amount\": \"10.50\",\n  \"asset\": \"USDC\",\n  \"chain\": \"solana\",\n  \"from\": \"7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2\",\n  \"to\": \"3xTd...recipient\",\n  \"network\": \"mainnet\",\n  \"router_version\": 2,\n  \"treat_as_gross_amount\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.platform.bitnob.com/sponsored-transfers")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"10.50\",\n  \"asset\": \"USDC\",\n  \"chain\": \"solana\",\n  \"from\": \"7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2\",\n  \"to\": \"3xTd...recipient\",\n  \"network\": \"mainnet\",\n  \"router_version\": 2,\n  \"treat_as_gross_amount\": true\n}")
  .asString();

{
  "fee": {
    "amount": "0.02",
    "asset": "USDC",
    "usd": "0.02"
  },
  "object": "sponsored_transfer",
  "partner_fee": {
    "address": "9xQe...partner",
    "amount": "0.20",
    "asset": "USDC",
    "usd": "0.20"
  },
  "recipient_amount": "10.50",
  "sign": {
    "scheme": "solana_ed25519"
  },
  "status": "quoted",
  "total_debit": "10.72"
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "type": "<string>"
  }
}

Authorizations

X-API-Key

string

header

required

Headers

API-Version

enum<string>

default:v1

API version (defaults to the latest supported version if omitted).

Available options:

v1

Idempotency-Key

string

required

Unique key (1-255 printable ASCII chars) used to safely retry write operations. Same key + body returns the cached response; same key + different body returns 409.

Required string length: 1 - 255

Body

application/json

amount

string

required

Decimal amount in the asset's normal units (not base units). By default the recipient receives this amount; with treat_as_gross_amount, this is the sender's total debit.

Example:

"10.50"

asset

string

required

Token symbol to transfer (a supported stablecoin), e.g. USDC on Solana/EVM or USDT on Tron.

Example:

"USDC"

chain

string

required

Chain to transfer on: solana, ethereum, base, arbitrum, optimism, polygon, bsc, or tron.

Example:

"solana"

from

string

required

Sender address. This is your end-user's own address, which holds the token and signs the transfer (and, on Tron for a first-time sender, the one-time approval).

Example:

"7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2"

string

required

Recipient address.

Example:

"3xTd...recipient"

network

string

Deprecated and ignored. The network follows the environment (live is mainnet, sandbox is testnet), so omit it. Any value sent is ignored, kept only for backward compatibility.

Example:

"mainnet"

partner_fee

object

Show child attributes

router_version

integer

Optional EVM paymaster router contract version. Omit for the chain default. Rejected if not allowed for the chain.

Required range: x >= 1

Example:

2

treat_as_gross_amount

boolean

Treat amount as the sender's total debit and deduct sponsorship and partner fees from the recipient amount.

Response

Created

asset

string

chain

string

confirmations

integer

created_at

string

expires_at

string

RFC 3339 quote expiry; present while status is quoted. Sign and submit before this time.

failure_code

string

Machine-readable failure reason on a failed transfer, e.g. insufficient_token_balance, transfer_reverts, reverted.

failure_reason

string

Human-readable failure detail.

fee

object

Bitnob sponsorship fee, charged in the transferred token.

Show child attributes

from

string

Transfer id; use it in the submit and get endpoints.

network

string

object

string

Object type discriminator; always "sponsored_transfer".

Example:

"sponsored_transfer"

partner_fee

object

Your markup breakdown; present only if you attached partner_fee on the quote.

Show child attributes

recipient_amount

string

What the recipient receives (decimal).

Example:

"10.50"

router_version

integer

The resolved EVM router contract version the transfer was quoted against (absent for non-EVM).

sign

object

What the end-user must sign; present only while status is quoted.

Show child attributes

status

string

Lifecycle status: quoted, validating, submitted, assembled (EVM only), tron_activating and tron_approving (Tron first-time onboarding), pending, completed, failed, expired, cancelled.

Example:

"quoted"

string

total_debit

string

What leaves the sender (decimal). In gross mode this equals amount; otherwise it equals recipient_amount + fee + partner_fee.

Example:

"10.72"

treat_as_gross_amount

boolean

Whether the request amount was treated as the sender's total debit.

tx_hash

string

On-chain transaction hash, set once broadcast.

Get started

Meta

Assets

Vaults

Wallets

Transactions

Gas stations

Sponsored transfers

Consolidation

Policies

KYT

Insights

Users

Subscriptions

Webhooks

RPC

Create sponsored transfer (quote)

Authorizations

Headers

Body

Response