Quotes API

A quote locks in an exchange rate for a USDC → local currency conversion. Create a quote before initiating a payout. Quotes are valid for 5 minutes and can only be used once.

POST/v1/quotes

Create a new FX quote. Returns the locked rate and a quote ID to use when creating a payout.

Create a quote

Request body

Field	Type	Required	Description
`source_amount_usdc`	`number`	Yes	Amount in whole USDC (e.g., `100` = $100). Min: 0.01
`target_currency`	`string`	Yes	Target fiat currency code. One of: `UGX`, `KES`, `NGN`, `GHS`, `TZS`
`idempotency_key`	`string`	Yes	Unique key to deduplicate requests. Max 128 chars.

Response

Field	Type	Description
`quote_id`	`string`	Unique quote identifier. Use this when creating a payout.
`source_currency`	`string`	Always `"USDC"`
`target_currency`	`string`	The requested target currency.
`source_amount`	`number`	Amount in USDC being converted.
`target_amount`	`number`	Amount in target currency the recipient will receive.
`exchange_rate`	`number`	Locked rate: target currency units per 1 USDC (inclusive of spread).
`spread_percent`	`number`	Settlra's margin, e.g. `0.01` = 1%.
`status`	`string`	`ACTIVE`, `LOCKED`, `USED`, or `EXPIRED`
`expires_at`	`string`	ISO 8601 timestamp. Quote expires 5 minutes after creation.
`created_at`	`string`	ISO 8601 timestamp.

curl example

bash

"color:#ff7b72">curl "color:#79c0ff">-X POST https://api-sandbox.settlra.com/v1/quotes \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key" \
  "color:#79c0ff">-H "Content-Type: application/json" \
  "color:#79c0ff">-d '{
    "source_amount_usdc": 500,
    "target_currency": "UGX",
    "idempotency_key": "quote-abc123"
  }'

Node.js example

javascript

"color:#ff7b72">const quote = "color:#ff7b72">await fetch('https://api-sandbox.settlra.com/v1/quotes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SETTLRA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source_amount_usdc: 500,
    target_currency: 'UGX',
    idempotency_key: 'quote-abc123',
  }),
}).then(r => r.json());

Response example

json

{
  "quote_id": "q_01j3ab4cd5ef6gh7ij8kl9mn0p",
  "source_currency": "USDC",
  "target_currency": "UGX",
  "source_amount": 500,
  "target_amount": 1871250,
  "exchange_rate": 3742.5,
  "spread_percent": 0.01,
  "status": "ACTIVE",
  "expires_at": "2024-07-01T12:05:00.000Z",
  "created_at": "2024-07-01T12:00:00.000Z"
}

GET/v1/quotes/:id

Retrieve a quote by ID to check its current status.

Get a quote

Path parameters

Parameter	Type	Description
`id`	`string`	The `quote_id` returned when the quote was created.

bash

"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/quotes/q_01j3ab4cd5ef6gh7ij8kl9mn0p \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key"

Quote lifecycle

Quotes transition through these states:

Status	Description
`ACTIVE`	Rate is locked and the quote can be used to create a payout.
`LOCKED`	A payout has been created with this quote; it is no longer available.
`USED`	The payout was successfully initiated using this quote.
`EXPIRED`	The 5-minute TTL elapsed. Create a new quote.

Error responses

Error code	HTTP status	Cause
`VALIDATION_ERROR`	400	Missing or invalid request fields.
`QUOTE_NOT_FOUND`	404	No quote with the given ID exists for your account.
`DUPLICATE_IDEMPOTENCY_KEY`	409	Same idempotency key used with different parameters.
`RATE_LIMIT_EXCEEDED`	429	Too many quote requests.