Technical integration overview

One API for cross-border payouts

Rook lets banks and fintechs ('Rook clients') send money into markets where they have no licence, presence, or correspondent bank. Rook connects you to licensed local partners that collect fiat at origin and pay out fiat at destination, and moves the value between them in USD₮.

Integrate once, and reach every corridor Rook routes. For each payment Rook prices every available path, picks the best one, and returns a single all-in rate. You never pick a provider and never see one: you send fiat or USD₮ to the instructions Rook returns, and your beneficiary is paid locally. Rook never holds your funds at any point.

Roles#

RoleWhat you doHow you earn
Fiat payout Request a quote from Rook, confirm it into an order, and pay the local fiat amount to the bank instructions Rook returns. Rook's partners convert it, move it in USD₮, and pay your beneficiary in the destination currency. Adding a margin when quoting payouts to your clients
Stablecoin payout Same flow, funded in USD₮. Rook returns an on-chain address instead of a bank account, and the destination partner pays your beneficiary in local fiat. Adding a margin when quoting payouts to your clients

Integration with the API#

Integrate through the Rook REST API: JSON over HTTPS, versioned under /v1. The full OpenAPI 3 description is published at /openapi.json, so you can generate a typed client in Go, TypeScript, Python, Java, or C# and focus on business logic.

Every request carries a bearer token from POST /v1/auth/sign-in/email. If your user belongs to more than one organization, send x-organization-id to say which one the call is for. You can only act for organizations you are a member of; anything else returns 403. Amounts and rates always travel as decimal strings, never as numbers.

EnvironmentBase URLReference
Sandboxhttps://api.sandbox.rooklabs.co/v1/docs · /redoc · /openapi.json
ProductionShared with you at go-liveSame paths as sandbox

First steps#

  1. 1

    Get sandbox access

    Create your user with POST /v1/auth/sign-up/email on the sandbox, using your work email, and send that email to your Rook contact. Rook creates your organization and adds you to it. Colleagues sign up the same way and Rook adds them too.

  2. 2

    Generate your client

    Download /openapi.json and generate a typed client in your language with any OpenAPI generator. Every endpoint, field and error is in that file.

  3. 3

    Sign in and keep your token

    Call POST /v1/auth/sign-in/email and send the token as Authorization: Bearer on every request. It lasts 24 hours. There are no keys to register.

  4. 4

    Run the sandbox checklist

    As your build nears completion, work through the sandbox checklist: quotes, orders, retries, expiry and an order followed to paid out. Sandbox partners are simulated, so no real money moves.

  5. 5

    Sandbox testing session

    We'll then arrange a session to run transactions end to end exactly as they will in production, including prefunding with real USD₮.

A typical payout#

End to end: three calls you make, one payment your client sends, and a status you follow to the end.

Click any call name for an example payload.

  1. 1

    Register the beneficiary

    You → RookPOST /v1/beneficiaries · The recipient's name, country, currency and bank details: CLABE for Mexico, routing and account for the US, IBAN for Europe, bank and account for Colombia. Do this once per recipient, not once per payment.
    {
      "currency": "MXN",
      "name": "Comercializadora Azteca S.A. de C.V.",
      "countryId": "MX",
      "bankName": "BBVA México",
      "accountNumber": "012180001234567890",
      "accountType": "checking",
      "extraDetails": { "rfc": "CAZ120315ABC" }
    }
    Rook → You201 Created · Returns the beneficiary id you will use on every order to this recipient.
    {
      "id": "84ecbd88-c083-49d6-a780-ef7da4b15e64",
      "name": "Comercializadora Azteca S.A. de C.V.",
      "countryId": "MX",
      "currency": "MXN",
      "createdAt": "2026-10-22T14:03:11.000Z"
    }

    FOR INFO · Rook registers the account in the background with every destination partner that serves that country. When you change bank details with PATCH /v1/beneficiaries/:id, Rook registers them again.

  2. 2

    Get a quote

    You → RookPOST /v1/rates/quote · What a currency pair and amount would cost. side: SEND fixes what you pay; side: RECEIVE fixes what the beneficiary gets. Free of side effects, so quote as often as you like.
    {
      "from": "USD",
      "to": "MXN",
      "amount": "1000.00",
      "side": "SEND",
      "toCountry": "MX"
    }
    Rook → You200 OK · The best path Rook found, as one all-in clientRate with Rook's fee already inside it. Valid until expiresAt (60 seconds).
    {
      "quoteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "from": "USD",
      "to": "MXN",
      "side": "SEND",
      "sendAmount": "1000.00",
      "receiveAmount": "18412.37",
      "clientRate": "18.41237",
      "expiresAt": "2026-10-22T14:05:12.000Z",
      "indicative": true,
      "legs": 2
    }
    Rook → You422 / 400 · Or there is nothing to quote: ROUTE_NOT_SUPPORTED (no path for this pair), NO_LIQUIDITY_AVAILABLE (paths exist but none priced right now; retry shortly) or AMOUNT_OUT_OF_BOUNDS (outside the corridor's minimum or maximum).

    FOR INFO · The quote is indicative. Each partner's real rate is recorded when the order executes, and any difference is borne by you. legs tells you whether the payment crosses one partner or two; the partners themselves are never exposed.

  3. 3

    Create the order

    You → RookPOST /v1/orders · The quoteId you want to lock in and the beneficiaryId to pay. A quote turns into exactly one order, so the quoteId is your idempotency key.
    {
      "quoteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "beneficiaryId": "84ecbd88-c083-49d6-a780-ef7da4b15e64"
    }
    Rook → You201 Created · The order in AWAITING_FIAT with paymentInstructions: a bank account and reference for fiat funding, or a chain and address for USD₮ funding. Pay before paymentInstructions.expiresAt (15 minutes).
    {
      "orderId": "b7a1c2e4-1f0d-4e55-9a7b-6a2e9c1d0f33",
      "status": "AWAITING_FIAT",
      "from": "USD",
      "to": "MXN",
      "sendAmount": "1000.00",
      "receiveAmount": "18412.37",
      "clientRate": "18.41237",
      "paymentInstructions": {
        "bankName": "Example Bank N.A.",
        "accountNumber": "210987654321",
        "routingNumber": "101019644",
        "holder": "Your organization (virtual account)",
        "reference": "ROOK-B7A1C2E4",
        "amount": "1000.00",
        "currency": "USD",
        "expiresAt": "2026-10-22T14:19:40.000Z"
      },
      "createdAt": "2026-10-22T14:04:40.000Z"
    }
    Rook → You422 · Or the quote has expired or was already used for another order. Nothing was created; request a new quote. If you are retrying after a timeout, look the order up with GET /v1/orders instead.
  4. 4

    Your client pays

    Off-API bank or chainFiat or USD₮ transfer · Your client sends exactly amount to the instructions from step 3, with the reference when there is one. Nothing to build here: no call is made. The money goes straight to the origin partner, never to Rook.

    FOR INFO · If the funds do not arrive before expiresAt, the order moves to EXPIRED and you need a new quote.

  5. 5

    Follow the order to its final state

    You → RookGET /v1/orders/:id · The current status plus a timeline of every status change and when it happened.
    {
      "orderId": "b7a1c2e4-1f0d-4e55-9a7b-6a2e9c1d0f33",
      "status": "PAID_OUT",
      "timeline": [
        { "previousStatus": null,            "newStatus": "CONFIRMED",     "source": "API",     "createdAt": "2026-10-22T14:04:40Z" },
        { "previousStatus": "CONFIRMED",     "newStatus": "AWAITING_FIAT", "source": "API",     "createdAt": "2026-10-22T14:04:40Z" },
        { "previousStatus": "AWAITING_FIAT", "newStatus": "FIAT_RECEIVED", "source": "WEBHOOK", "createdAt": "2026-10-22T14:11:02Z" },
        { "previousStatus": "FIAT_RECEIVED", "newStatus": "USDT_SENT",     "source": "WORKER",  "createdAt": "2026-10-22T14:11:30Z" },
        { "previousStatus": "USDT_SENT",     "newStatus": "USDT_RECEIVED", "source": "WEBHOOK", "createdAt": "2026-10-22T14:12:15Z" },
        { "previousStatus": "USDT_RECEIVED", "newStatus": "PAID_OUT",      "source": "WEBHOOK", "createdAt": "2026-10-22T14:13:48Z" }
      ]
    }
    Rook → YouPAID_OUT · The funds reached the beneficiary. This is the success state.
    Rook → YouPAYOUT_FAILED · Or the destination rail rejected the payout. It then moves to REFUNDED once the value is returned, or to EXCEPTION while Rook operations resolve it.

    FOR INFO · RETURNED can still follow PAID_OUT when the beneficiary's bank sends the money back days later, so keep reconciling paid orders. GET /v1/notifications gives you the same events as one feed across all your orders.

Every order follows one path: AWAITING_FIAT → FIAT_RECEIVED → USDT_SENT → USDT_RECEIVED → PAID_OUT. A single-partner corridor can go straight from FIAT_RECEIVED to PAID_OUT. EXPIRED, REFUNDED and RETURNED are final and never move again.

How the money moves#

Rook does not hold client funds or wallet keys at any stage. Your client pays the origin partner, that partner converts to USD₮ and sends it on-chain to the destination partner, and the destination partner pays the beneficiary over a local rail. Rook prices the path, sends the instructions, and records every step.

Value moves between partners in USD₮ on the chain each corridor uses:

EthereumPolygonSolanaTron

When you fund in USD₮, send it from a wallet you control to the address in paymentInstructions, on the chain named there. Addresses can be specific to one order, so always read them from the order and never reuse one from an earlier payment.

Rounding always protects the quote: on SEND quotes what the beneficiary receives is rounded down (2 decimals for fiat, 6 for USD₮); on RECEIVE quotes what you must send is rounded up. Rook's own revenue is settled with its partners at the end of each day and is never deducted from your payment in flight.

Errors you should handle#

CodeStatusWhat to do
ROUTE_NOT_SUPPORTED422Rook has no path for this pair or country. Ask us to open the corridor.
NO_LIQUIDITY_AVAILABLE422Paths exist but none priced right now. Retry in a few seconds.
AMOUNT_OUT_OF_BOUNDS400Outside the corridor's minimum or maximum. Resize or split the payment.
INVALID_AMOUNT400Too many decimals for the currency (at most 6, fewer for most fiat).
Quote expired or already used422Request a new quote, or find the existing order with GET /v1/orders.
Organization not allowed403Your user is not a member of the organization in x-organization-id.

Full reference#

This page covers what you need to integrate and go live. The full documentation covers every concept, endpoint, field and error of the public API.

Open the documentation

Prefer to talk it through?#

If anything here is easier to clarify on a call than over messages, ask your Rook contact for a technical session and we'll walk through it together.