Skip to main content

​
Prerequisites

  • An API key (service key) from the Switch dashboard.
  • HTTP client (e.g. cURL, Postman, or your application).

​
Step 1: Get your API key

  1. Sign in to the Switch dashboard.
  2. Create or select a project and obtain your service key (API key).
  3. Use the sandbox key for testing; use the live key for production.
The same base URL is used for both; the key type (sandbox vs live) determines which environment you hit.

​
Step 2: Authenticate requests

Include your service key in every request using the x-service-key header: 
curl -X GET "https://api.onswitch.xyz/coverage?direction=OFFRAMP" \
  -H "x-service-key: YOUR_SERVICE_KEY"
Never expose your API key in client-side code or public repositories. Use environment variables or a secrets manager.

​
Step 3: Check coverage

Before building flows, see which countries and currencies are supported: 
curl -X GET "https://api.onswitch.xyz/coverage?direction=OFFRAMP" \
  -H "x-service-key: YOUR_SERVICE_KEY"
Use direction=ONRAMP or direction=SWAP to see onramp or swap coverage.

​
Step 4: Get field requirements

For offramp or onramp, you must collect beneficiary details. Requirements depend on country, currency, and channel: 
curl -X GET "https://api.onswitch.xyz/requirement?direction=OFFRAMP&country=NG&currency=NGN&type=INDIVIDUAL" \
  -H "x-service-key: YOUR_SERVICE_KEY"
The response describes which fields to collect (e.g. bank_code, account_number, holder_name) and how to validate them.

​
Step 5: Get a quote and initiate (offramp example)

  1. Quote — Get rate and fees for an amount:
curl -X POST "https://api.onswitch.xyz/offramp/quote" \
  -H "x-service-key: YOUR_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "country": "NG",
    "asset": "base:usdc",
    "currency": "NGN"
  }'
  1. Initiate — Create the transaction with beneficiary details (from the requirement response):
curl -X POST "https://api.onswitch.xyz/offramp/initiate" \
  -H "x-service-key: YOUR_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "country": "NG",
    "asset": "base:usdc",
    "currency": "NGN",
    "beneficiary": {
      "holder_type": "INDIVIDUAL",
      "holder_name": "Jane Doe",
      "bank_code": "058",
      "account_number": "0123456789"
    }
  }'
  1. The response includes a deposit object: amount, wallet address, and asset. Your user sends that amount of stablecoin to that address. After the deposit is detected, the payout to the beneficiary is processed.
  2. Use webhooks or the Status endpoint to track the transaction.

​
Next steps