New to the Ramp API? Read the Ramp API Overview for the full lifecycle and all three transaction flows.
Endpoint
POST{{baseURL}}/v1/ramp/quote
Request headers
| Header | Value | Required | Description |
|---|---|---|---|
Content-Type | application/json | Yes | Specifies that the request body is JSON. |
x-api-key | YOUR_API_KEY | Yes | API key for authentication. |
Request body
copy
{
"paymentChannel": "BANK_TRANSFER",
"source": {
"amount": 20000,
"country": "NG",
"currency": "NGN"
},
"target": {
"symbol": "USDT",
"blockchain": "MATIC"
},
"feeLevel": {
"type": "MEDIUM"
},
"recipient": {
"address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9",
"network": {
"blockchain": "MATIC",
"tokenStandard": "ERC20"
}
}
}
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
paymentChannel | string | Yes | How fiat funds are collected (e.g. BANK_TRANSFER). |
source.amount | number | Yes | Amount of fiat to convert. |
source.country | string | Yes | ISO 3166-1 alpha-2 code for the sender country (e.g. NG). |
source.currency | string | Yes | ISO 4217 code for the fiat currency (e.g. NGN). |
target.symbol | string | Yes | Token symbol of the target crypto asset (e.g. USDT). |
target.blockchain | string | Yes | Blockchain network for the target asset (e.g. MATIC). |
feeLevel.type | string | No | Gas fee level: LOW, MEDIUM, or HIGH. Defaults to MEDIUM. |
recipient.address | string | Yes | Wallet address where crypto will be delivered. |
recipient.network.blockchain | string | Yes | Blockchain network for the recipient wallet. |
recipient.network.tokenStandard | string | Yes | Token standard (e.g. ERC20). |
Onramp quotes require recipient details — unlike offramp, the onramp quote needs the full
recipient object (address + network) at quote creation time.Request examples
curl --request POST '{{baseURL}}/v1/ramp/quote' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"paymentChannel": "BANK_TRANSFER",
"source": {
"amount": 20000,
"country": "NG",
"currency": "NGN"
},
"target": {
"symbol": "USDT",
"blockchain": "MATIC"
},
"feeLevel": {
"type": "MEDIUM"
},
"recipient": {
"address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9",
"network": {
"blockchain": "MATIC",
"tokenStandard": "ERC20"
}
}
}'
const payload = {
paymentChannel: 'BANK_TRANSFER',
source: {
amount: 20000,
country: 'NG',
currency: 'NGN'
},
target: {
symbol: 'USDT',
blockchain: 'MATIC'
},
feeLevel: {
type: 'MEDIUM'
},
recipient: {
address: '0xd62acd62fdb155afaa5d12c6caf01119d413dfd9',
network: {
blockchain: 'MATIC',
tokenStandard: 'ERC20'
}
}
};
fetch('{{baseURL}}/v1/ramp/quote', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then((res) => {
if (!res.ok) throw new Error(`Request failed with status ${res.status}`);
return res.json();
})
.then((body) => console.log(body))
.catch((error) => console.error('Failed to create onramp quote', error));
import requests
url = "{{baseURL}}/v1/ramp/quote"
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"paymentChannel": "BANK_TRANSFER",
"source": {
"amount": 20000,
"country": "NG",
"currency": "NGN",
},
"target": {
"symbol": "USDT",
"blockchain": "MATIC",
},
"feeLevel": {
"type": "MEDIUM",
},
"recipient": {
"address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9",
"network": {
"blockchain": "MATIC",
"tokenStandard": "ERC20",
},
},
}
response = requests.post(url, json=payload, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
const axios = require('axios');
axios.post('{{baseURL}}/v1/ramp/quote', {
paymentChannel: 'BANK_TRANSFER',
source: {
amount: 20000,
country: 'NG',
currency: 'NGN'
},
target: {
symbol: 'USDT',
blockchain: 'MATIC'
},
feeLevel: {
type: 'MEDIUM'
},
recipient: {
address: '0xd62acd62fdb155afaa5d12c6caf01119d413dfd9',
network: {
blockchain: 'MATIC',
tokenStandard: 'ERC20'
}
}
}, {
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
timeout: 30000
})
.then((response) => console.log(response.data))
.catch((error) => {
if (error.response) {
console.error('API error:', error.response.data);
} else {
console.error('Request error:', error.message);
}
});
Successful response
copy
{
"message": "quote successfully created",
"status": "success",
"data": {
"id": "b7e166bf-9f58-479d-8867-f655a47334d5",
"source": {
"currency": "NGN",
"country": "NG",
"amount": 20000,
"type": "FIAT"
},
"target": {
"currency": "Tether",
"symbol": "USDT",
"blockchain": "MATIC",
"amount": 13.33,
"type": "CRYPTOCURRENCY"
},
"quoteCurrency": "NGN",
"rate": 1500,
"fee": {
"amount": 20000,
"gas": {}
},
"rules": [
{
"category": "LIMIT",
"appliedCurrency": "Tether",
"transaction": {
"minimum": 1,
"maximum": 10000
},
"invoice": 10000
}
],
"summary": {
"total": 20000
},
"settlement": "Same Day"
}
}
Response field reference
| Field | Type | Description |
|---|---|---|
data.id | string | Unique quote identifier — pass to POST /v2/ramp/payout. |
data.source.currency | string | Fiat currency code (e.g. NGN). |
data.source.country | string | Sender country code (e.g. NG). |
data.source.amount | number | Fiat amount the sender pays. |
data.source.type | string | Asset type — FIAT. |
data.target.currency | string | Full name of the target token (e.g. Tether). |
data.target.symbol | string | Token symbol (e.g. USDT). |
data.target.blockchain | string | Target blockchain network. |
data.target.amount | number | Amount of crypto the recipient receives. |
data.target.type | string | Asset type — CRYPTOCURRENCY. |
data.quoteCurrency | string | Currency context for the quote rate. |
data.rate | number | Exchange rate applied (e.g. 1 USDT = 1500 NGN). |
data.fee.amount | number | Fee amount charged. |
data.fee.gas | object | Gas fee details (may be empty). |
data.rules | array | Corridor-level transaction limits. |
data.rules[].category | string | Rule category (e.g. LIMIT). |
data.rules[].appliedCurrency | string | Currency the limit applies to. |
data.rules[].transaction.minimum | number | Minimum transaction amount. |
data.rules[].transaction.maximum | number | Maximum transaction amount. |
data.rules[].invoice | number | Invoice threshold. |
data.summary.total | number | Total fiat debit amount. |
data.settlement | string | Estimated settlement time (e.g. Same Day). |
Error responses
| Status | Error Code | Message | Description |
|---|---|---|---|
| 400 | INVALID_INPUT | Invalid request payload | One or more fields are missing or have invalid values. |
| 400 | INVALID_INPUT | Invalid country or currency ISO code | Source/target country or currency combination is unsupported. |
| 401 | UNAUTHORIZED | Missing or invalid API key | The x-api-key header is missing or incorrect. |
| 403 | FORBIDDEN | Access denied | The authenticated user is not allowed to create quotes. |
| 404 | NOT_FOUND | Resource not found | The requested corridor or token does not exist. |
| 500 | SERVER_ERROR | Internal server error | An unexpected error occurred on the server. |
Best practices
- The onramp flow requires the full
recipientobject (address + network) at quote time — this differs from offramp. - Use
tokenStandard: "ERC20"for EVM-compatible chains. Other standards may be supported in future. - Validate the
rules[].transaction.minimumandrules[].transaction.maximumbefore proceeding to payout. - The
settlementfield gives an ETA for token delivery — surface this in your UI.
Next steps
- Create Ramp Payout — execute the onramp transfer.
- Create Quote (Crypto) — for crypto-to-crypto transfers.
- Create Quote (Offramp) — for crypto-to-fiat conversions.