The API

Every request carries a bearer token. A session token is short lived and is intended for interactive use; an API key is for your systems and is scoped to a subset of what your own role can do. A key can never hold authority you do not have.

curl http://api.railway.internal:8000/api/v1/conversions \
  -H "Authorization: Bearer ${VAPS_API_KEY}"

Send an Idempotency-Key header on every request that moves money. A retry with the same key returns the original result rather than acting twice. This matters most when a request times out: the safe response to a timeout is to retry with the same key, never to send a new one.

curl -X POST http://api.railway.internal:8000/api/v1/conversions \
  -H "Authorization: Bearer ${VAPS_API_KEY}" \
  -H "Idempotency-Key: 8f14e45f-ea1a-4a52-9c9f-2c1f7f2f8d21" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_...",
    "source_asset": "GHS",
    "source_amount": "500000.00",
    "destination_asset": "USDC",
    "destination_network": "BASE",
    "destination_address": "0x..."
  }'

Note what is absent from that body: no rate, no fee and no venue. Those are outputs, and a request carrying one is refused rather than quietly stripped.

Paying a supplier invoice is the other question: not "what will GHS 5,000 buy" but "what does 500 USDC cost". Send destination_amount instead of source_amount, and the cost is quoted back to you. Exactly one of the two, and sending both is refused.

curl -X POST http://api.railway.internal:8000/api/v1/conversions   -H "Authorization: Bearer ${VAPS_API_KEY}"   -H "Idempotency-Key: 2f9c1b7e-3d64-4f18-9a02-7b5d1c8e4a63"   -H "Content-Type: application/json"   -d '{
    "customer_id": "cus_...",
    "source_asset": "GHS",
    "destination_amount": "500.00",
    "delivery": "EXACT",
    "destination_asset": "USDC",
    "destination_network": "BASE",
    "destination_address": "0x..."
  }'

Fixing a quantity is not fixing a price. The rate, the fees, the venue and the cost are still ours to derive, and a value you send for any of them is still refused.

Under EXACT the venue commits to the figure: the execution floor is the target itself, so a venue that cannot fill it does not execute at all and your funds are released. Fewer venues quote, because committing means carrying the risk of landing on it. Under TOLERATED the usual deviation applies and the receiver may get slightly less.

source_amount is null on the conversion until a venue has quoted, and nothing is reserved until you accept. Read it as "not yet known", never as zero.

1. 1. POST a conversion. It enters compliance review. Nothing has moved.
2. 2. Poll the conversion, or subscribe to webhooks, until it is awaiting acceptance.
3. 3. GET the quotes. Each carries the venue's rate, the destination amount and every fee component.
4. 4. POST the acceptance with the quote id. Expiry is checked at that moment, not before.
5. 5. The venue executes and delivers to your address. GET the execution record for what actually filled.

The delivered amount is the venue's actual fill, which can differ from the quote within the agreed tolerance. A fill outside it fails the conversion and releases your funds.

Each delivery carries a signature over the raw request body and a timestamp. Verify the signature against the bytes you received, before parsing them, and reject a timestamp outside your tolerance. Every attempt, including the failures, is retained in a delivery log you can read.

A webhook is a notification, not a source of truth. Treat it as a signal to read the resource, and never as an instruction to move money on its own.

Errors carry a machine-readable code, a message, and the request id. Quote the request id when contacting support: it finds the exact request in our logs.

{
  "error": {
    "code": "quote_expired",
    "message": "This quote has expired.",
    "request_id": "req_01J..."
  }
}

One code deserves special handling. If a conversion reports EXECUTION_UNKNOWN, do not retry it. The outcome is genuinely undetermined and a retry could execute twice. Read the conversion and wait; it is resolved by a person, not by a timer.