Skip to main content
POST
/
swap
/
initiate
Initiate
curl --request POST \
  --url https://api.onswitch.xyz/swap/initiate \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: <api-key>' \
  --data '
{
  "amount": 100,
  "from_asset": "base:usdc",
  "to_asset": "solana:usdt",
  "beneficiary": {
    "wallet_address": "0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a"
  },
  "exact_output": false,
  "callback_url": "https://your-app.com/webhook",
  "reference": "a3f9c2e1-7b4d-4a8e-9c62-1d8f4e6b2a90",
  "developer_fee": 0.5,
  "developer_recipient": "0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a",
  "refund_address": "0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a"
}
'
{
  "success": true,
  "message": "Swap initiated successfully",
  "timestamp": "2026-04-18T14:22:08.631Z",
  "data": {
    "status": "AWAITING_DEPOSIT",
    "type": "SWAP",
    "reference": "a3f9c2e1-7b4d-4a8e-9c62-1d8f4e6b2a90",
    "rate": 1,
    "fee": {
      "total": 0.5,
      "platform": 0.45,
      "developer": 0.05,
      "currency": "USDC"
    },
    "source": {
      "amount": 100,
      "currency": "USDC"
    },
    "destination": {
      "amount": 99.5,
      "currency": "USDT"
    },
    "deposit": {
      "amount": 100,
      "address": "0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a",
      "asset": "base:usdc",
      "note": [
        "Kindly send the exact amount to the wallet address to complete the transaction.",
        "This dynamic wallet address has a 30 minutes expiry window and can only be used once."
      ]
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.onswitch.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

x-service-key
string
header
required

Service key for API authentication

Body

application/json
amount
number
required
Required range: x >= 0
from_asset
enum<string>
required
Available options:
base:usdc,
solana:usdc,
solana:usdt,
ethereum:usdc,
ethereum:usdt,
polygon:usdc,
polygon:usdt,
bsc:usdc,
bsc:usdt,
arbitrum:usdc,
optimism:usdc,
gnosis:usdc,
gnosis:usdt,
arbitrum:usdt,
avalanche:usdc,
monad:usdc,
optimism:usdt,
monad:usdt,
plasma:usdt,
avalanche:usdt,
tron:usdt,
linea:usdt,
mantle:usdt,
hyperevm:usdt,
berachain:usdt,
linea:usdc,
berachain:usdc,
sonic:usdc,
base:cngn,
bsc:cngn
to_asset
enum<string>
required
Available options:
base:usdc,
solana:usdc,
solana:usdt,
ethereum:usdc,
ethereum:usdt,
polygon:usdc,
polygon:usdt,
bsc:usdc,
bsc:usdt,
arbitrum:usdc,
optimism:usdc,
gnosis:usdc,
gnosis:usdt,
arbitrum:usdt,
avalanche:usdc,
monad:usdc,
optimism:usdt,
monad:usdt,
plasma:usdt,
avalanche:usdt,
tron:usdt,
linea:usdt,
mantle:usdt,
hyperevm:usdt,
berachain:usdt,
linea:usdc,
berachain:usdc,
sonic:usdc,
base:cngn,
bsc:cngn
beneficiary
Receive to saved beneficiary · object
required

The recipient of the swap transaction.

exact_output
boolean
default:false
callback_url
string<uri>

Webhook URL to receive transaction status updates.

reference
string<uuid>
developer_fee
number

Optional developer fee percentage (0-100)

Required range: 0 <= x <= 100
developer_recipient
string

Optional wallet address to receive developer fee.

refund_address
string

Optional wallet address to receive refunds for failed/expired deposits. The refund address must be on the same blockchain specified for the payment.

Response

Successfully initiated swap transaction

success
boolean
required
message
string
required
timestamp
string<date-time>
required
data
object
required

Response data