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": 2,
"symbol": "USDC",
"blockchain": "MATIC"
},
"target": {
"symbol": "USDC",
"blockchain": "MATIC"
},
"feeLevel": {
"type": "MEDIUM"
},
"recipient": {
"address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9"
}
}
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
paymentChannel | string | Yes | Payment delivery channel (e.g. BANK_TRANSFER). |
source.amount | number | Yes | Amount of the source cryptocurrency to send. |
source.symbol | string | Yes | Token symbol of the source asset (e.g. USDC, USDT, POL). |
source.blockchain | string | Yes | Blockchain network for the source asset (e.g. MATIC). |
target.symbol | string | Yes | Token symbol of the target asset. |
target.blockchain | string | Yes | Blockchain network for the target asset. |
feeLevel.type | string | No | Gas fee level: LOW, MEDIUM, or HIGH. Defaults to MEDIUM. |
recipient.address | string | Yes | External wallet address where crypto will be delivered. |
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": 2,
"symbol": "USDC",
"blockchain": "MATIC"
},
"target": {
"symbol": "USDC",
"blockchain": "MATIC"
},
"feeLevel": {
"type": "MEDIUM"
},
"recipient": {
"address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9"
}
}'
const payload = {
paymentChannel: 'BANK_TRANSFER',
source: {
amount: 2,
symbol: 'USDC',
blockchain: 'MATIC'
},
target: {
symbol: 'USDC',
blockchain: 'MATIC'
},
feeLevel: {
type: 'MEDIUM'
},
recipient: {
address: '0xd62acd62fdb155afaa5d12c6caf01119d413dfd9'
}
};
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 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": 2,
"symbol": "USDC",
"blockchain": "MATIC",
},
"target": {
"symbol": "USDC",
"blockchain": "MATIC",
},
"feeLevel": {
"type": "MEDIUM",
},
"recipient": {
"address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9",
},
}
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: 2,
symbol: 'USDC',
blockchain: 'MATIC'
},
target: {
symbol: 'USDC',
blockchain: 'MATIC'
},
feeLevel: {
type: 'MEDIUM'
},
recipient: {
address: '0xd62acd62fdb155afaa5d12c6caf01119d413dfd9'
}
}, {
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": "318f21d8-2dd1-4321-b218-881fbdb64484",
"source": {
"currency": "USDC",
"symbol": "USDC",
"blockchain": "MATIC",
"amount": 2,
"type": "CRYPTOCURRENCY"
},
"target": {
"currency": "USDC",
"symbol": "USDC",
"blockchain": "MATIC",
"amount": 2,
"type": "CRYPTOCURRENCY"
},
"quoteCurrency": "USDC",
"rate": 1,
"fee": {
"symbol": "USDC",
"amount": 2,
"gas": {}
},
"rules": [
{
"category": "LIMIT",
"appliedCurrency": "USDC",
"transaction": {
"minimum": 0.01,
"maximum": 2000
},
"invoice": 300
}
],
"summary": {
"total": 3.25
},
"settlement": "100 hrs"
}
}
Response field reference
| Field | Type | Description |
|---|---|---|
data.id | string | Unique quote identifier — pass to POST /v2/ramp/payout. |
data.source | object | Details of the source cryptocurrency. |
data.source.currency | string | Full name of the source currency. |
data.source.symbol | string | Token symbol (e.g. USDC). |
data.source.blockchain | string | Blockchain network (e.g. MATIC). |
data.source.amount | number | Amount of source crypto. |
data.source.type | string | Asset type — always CRYPTOCURRENCY. |
data.target | object | Details of the target cryptocurrency. |
data.target.currency | string | Full name of the target currency. |
data.target.symbol | string | Token symbol. |
data.target.blockchain | string | Blockchain network. |
data.target.amount | number | Amount of target crypto the recipient receives. |
data.target.type | string | Asset type — always CRYPTOCURRENCY. |
data.quoteCurrency | string | Currency context for the quote rate. |
data.rate | number | Exchange rate applied (1:1 for same-token transfers). |
data.fee.symbol | string | Currency symbol for fees. |
data.fee.amount | number | Fee amount charged. |
data.fee.gas | object | Gas fee details (populated when gas applies). |
data.rules | array | Corridor-level transaction limits. |
data.rules[].category | string | Rule category (e.g. LIMIT). |
data.rules[].appliedCurrency | string | Currency to which the limit applies. |
data.rules[].transaction.minimum | number | Minimum allowed transaction amount. |
data.rules[].transaction.maximum | number | Maximum allowed transaction amount. |
data.rules[].invoice | number | Invoice threshold — amounts above this require documentation. |
data.summary.total | number | Total amount to debit (source + fees). |
data.settlement | string | Estimated time for the transfer to settle. |
Error responses
| Status | Error Code | Message | Description |
|---|---|---|---|
| 400 | INVALID_INPUT | Invalid request payload | One or more fields are missing or have invalid values. |
| 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 network or currency does not exist. |
| 500 | SERVER_ERROR | Internal server error | An unexpected error occurred on the server. |
Best practices
- Always specify the
feeLevelto control gas costs. If omitted,MEDIUMis used. - Use the
rulesarray to validate the requested amount is within corridor limits before calling payout. - Cache the
quoteIdtemporarily so the user can review fees before confirming. - Pass the
quoteIdtoPOST /v2/ramp/payoutto execute the transfer.
Next steps
- Create Ramp Payout — execute the transfer using the quote.
- Create Quote (Offramp) — convert crypto to fiat.
- Create Quote (Onramp) — convert fiat to crypto.