Onramp

Onramp transaction endpoints for converting fiat currency to stablecoins

Get onramp rate

post

Get the current exchange rate for an onramp transaction.

Authorizations

ServiceKey

Body

application/json

assetstring · enumRequiredPossible values:

countrystringRequired

ISO 3166-1 alpha-2 country code

currencystringOptional

Optional currency code. If not specified, defaults to the country's local currency.

Responses

200

Successfully retrieved onramp rate

application/json

400

Bad request - Invalid input parameters or validation error

application/json

post

/onramp/rate

HTTPcURLJavaScriptPython

POST /onramp/rate HTTP/1.1
Host: api.onswitch.xyz
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "asset": "base:usdc",
  "country": "NG",
  "currency": "NGN"
}

{
  "success": true,
  "message": "Onramp rate fetched successfully",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "rate": 1500.5
  }
}

Get onramp quote

post

Get a real-time quote for an onramp transaction including exchange rate, settlement time, and payment rail information.

Authorizations

ServiceKey

Body

application/json

amountnumberRequired

countrystring · enumRequiredPossible values:

assetstring · enumRequiredPossible values:

currencystring · enumOptional

Optional currency code. If not specified, defaults to the country's local currency.

Possible values:

channelstring · enumOptional

Optional transfer channel. If not specified, defaults to the country's default channel.

Possible values:

exact_outputbooleanOptionalDefault: false

developer_feenumber · max: 100Optional

Optional developer fee percentage (0-100)

Responses

200

Successfully retrieved onramp quote

application/json

400

Bad request - Invalid input parameters or validation error

application/json

post

/onramp/quote

HTTPcURLJavaScriptPython

POST /onramp/quote HTTP/1.1
Host: api.onswitch.xyz
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "amount": 150050,
  "country": "NG",
  "asset": "base:usdc",
  "currency": "NGN",
  "channel": "BANK",
  "exact_output": false,
  "developer_fee": 0.5
}

{
  "success": true,
  "message": "Quote fetched successfully",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "rate": 1500.5,
    "expiry": "2024-01-01T00:05:00.000Z",
    "settlement": "Same day",
    "channel": "BANK",
    "fee": {
      "total": 5,
      "platform": 4.5,
      "developer": 0.5,
      "currency": "NGN"
    },
    "fee_inclusive": true,
    "source": {
      "amount": 150050,
      "currency": "NGN"
    },
    "destination": {
      "amount": 100,
      "currency": "USDC"
    }
  }
}

Initiate onramp transaction

post

Initiate a fiat to stablecoin transaction.

Authorizations

ServiceKey

Body

application/json

amountnumberRequired

countrystring · enumRequiredPossible values:

currencystring · enumOptional

Optional currency code. If not specified, defaults to the country's local currency.

Possible values:

assetstring · enumRequiredPossible values:

exact_outputbooleanOptionalDefault: false

callback_urlstring · uriOptional

referencestring · uuidOptional

channelstring · enumOptional

Optional transfer channel. If not specified, defaults to the country's default channel.

Possible values:

reasonstring · enumOptional

Optional payment reason for compliance purposes

Possible values:

developer_feenumber · max: 100Optional

Optional developer fee percentage (0-100)

Responses

200

Successfully initiated onramp transaction

application/json

400

Bad request - Invalid input parameters or validation error

application/json

post

/onramp/initiate

HTTPcURLJavaScriptPython

POST /onramp/initiate HTTP/1.1
Host: api.onswitch.xyz
Content-Type: application/json
Accept: */*
Content-Length: 385

{
  "amount": 150050,
  "country": "NG",
  "currency": "NGN",
  "asset": "base:usdc",
  "beneficiary": {
    "holder_type": "INDIVIDUAL",
    "holder_name": "John Doe",
    "wallet_address": "0x1234567890123456789012345678901234567890"
  },
  "exact_output": false,
  "callback_url": "https://your-app.com/webhooks/onramp",
  "reference": "550e8400-e29b-41d4-a716-446655440000",
  "channel": "BANK",
  "reason": "REMITTANCES",
  "developer_fee": 0.5
}

{
  "success": true,
  "message": "Onramp initiated successfully",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "status": "PENDING",
    "type": "ONRAMP",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "payload": null,
    "source": {
      "amount": 150050,
      "currency": "NGN"
    },
    "destination": {
      "amount": 100,
      "currency": "USDC"
    },
    "deposit": {
      "bank_name": "Example Bank",
      "bank_code": "058",
      "account_name": "Your Company Name",
      "account_number": "0123456789",
      "note": [
        "Deposit exactly 150,050 NGN to the account above",
        "Include the reference in the payment narration"
      ]
    }
  }
}