Take a Quote in One Call

The express quote collapses the pricing step. Instead of creating an intent and then fetching the quote it produced, you send one call and get a priced, allocated quote straight back. Everything after pricing is unchanged — you still accept, authorize and complete.

What you’ll need

Your secret key.
The accountId you are settling into, from Read Your Balances.
A pair with real liquidity behind it — see Find a Liquidity Provider.

Express quote lives on the exchange base URL (/exchange/api/v1), but accept, authorize, status and complete are on /partners/marketplace/quote/{id}/.... This guide shows the full path on every call — do not assume one prefix for the whole flow.

Express vs. the intent flow

Intent flow — two calls to price

POST /partners/marketplace/intent returns a quote with a ttl, and you can inspect or negotiate before committing.

Express — one call to price

POST /partners/marketplace/express/quote returns the same priced quote directly.

From here they are identical

Accept, authorize, poll, complete — the same four calls on the same paths.

	Intent flow	Express
Calls to get a priced quote	2	1
Endpoint	`/partners/marketplace/intent`	`/partners/marketplace/express/quote`
Returns `allocationResult`	yes	yes
Returns `ttl` on the quote	yes (e.g. 899)	no
Accept / authorize / complete	same	same

The real difference is the ttl. The intent flow hands you a quote with a countdown you can show a customer before they commit. Express gives you no ttl until you accept — so express suits a flow where you price and commit in one motion, and the intent flow suits one where a human is deciding.

Step 1: Create the express quote

curl -X POST https://api.hyperrails.io/exchange/api/v1/partners/marketplace/express/quote \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "GHS",
    "destinationCurrency": "NGN",
    "amount": 5,
    "amountDirection": "source",
    "accountId": "0eb2090c-c046-4609-8fcc-0b7ef4dde30f"
  }'

Field	Required	What it is
`sourceCurrency`	yes	What the buyer pays in
`destinationCurrency`	yes	What you receive
`amount`	yes	How much
`amountDirection`	no	`source` or `destination`. Defaults to `source`
`accountId`	yes	The account you settle into
`externalReference`	no	Your own tracking reference

{
  "quoteId": "806dc37d-7880-4c8a-b871-c81e48a47438",
  "status": "PENDING",
  "source": "GHS",
  "destination": "NGN",
  "amount": 5.17301038,
  "totalSourceAmount": 5.17301038,
  "totalDestinationAmount": 578.0,
  "clientId": "afe5e863-f256-4244-8dd8-b6b9af7ec009",
  "mode": "test",
  "allocationResult": {
    "allocations": [
      {
        "allocatedAmount": 578.00000208,
        "clientId": "22f5ffc8-fecf-4fd8-acae-41cdb943b5b1",
        "id": "b73e12e8-a41e-426d-bb63-707109f4898a",
        "inverseRate": 0.008650519,
        "poolAccountId": "90472efa-9e90-4eea-8a1f-03da49f330ca",
        "poolId": "12798236-1916-40c5-acc2-843adb43cdd3",
        "poolType": "FUNDED",
        "rate": 115.6,
        "reference": "HPR-ALO-1bbe8b80e32e42578b6aeb14f9276ada",
        "sourceAmount": 5,
        "status": "PENDING",
        "weight": "BASE"
      }
    ],
    "fullAllocation": true,
    "totalDestinationAmount": 578.0,
    "totalSourceAmount": 5,
    "weightedAverageRate": 115.6,
    "weightedAverageRateInverse": 0.0087
  },
  "metadata": {
    "transactionFee": {
      "feeType": "flat",
      "currency": "NGN",
      "flatFee": 20.0,
      "percentageRate": 0.0,
      "appliedAmount": 578.0,
      "calculatedFee": 20.0
    }
  }
}

Keep the quoteId.

amount means the source amount here, despite what you may read elsewhere. Sending amount: 5 with amountDirection: "source" produced a trade of 5 GHS in and 578 NGN out. Some reference material describes amount as the destination amount — it is not, when amountDirection is source. Set amountDirection explicitly and check totalSourceAmount against what you expect before accepting.

amount (5) and totalSourceAmount (5.17301038) differ by the fee of 0.17301038 — the buyer pays slightly more than the headline amount. The separate transactionFee of 20.00 NGN is charged on the destination side. Two fees, two currencies.

A payment block is accepted here but does nothing. You can pass the buyer’s mobile money details to this call and it will return 200 — but the response has no metadata.mobileMoneyPayIn and the status is PENDING, not AWAITING_PAYMENT. No phone is charged. Express prices the trade; it does not start the payment. You still need Step 2.

externalReference is not an idempotency key at this step. Sending the same reference twice produced two different quotes with two different quoteIds, both 200. Retrying a timed-out express quote can leave you with duplicate quotes. Track the quoteId yourself and cancel any you abandon.

The pair must have real liquidity. Asking for more than a provider holds returns 400 "Unable to fulfill requested volume at the moment." — a different error from "No providers available", which means nobody trades the pair at all. See Find a Liquidity Provider.

Step 2: Accept the quote and charge the buyer

From here the flow is identical to the intent flow. Note the path drops express:

curl -X PUT https://api.hyperrails.io/exchange/api/v1/partners/marketplace/quote/QUOTE_ID/accept \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "0eb2090c-c046-4609-8fcc-0b7ef4dde30f",
    "payment": {
      "channel": "mobile_money",
      "countryCode": "GH",
      "mobileMoney": {
        "code": "mtn",
        "phoneNumber": "0244123456"
      }
    }
  }'

Do not leave express in the accept path. Calling /partners/marketplace/express/quote/{id}/accept returns 401 with a completely empty body — no JSON, no error code. It looks like an auth failure on a perfectly good key. The accept path has no express segment.

{
  "quoteId": "806dc37d-7880-4c8a-b871-c81e48a47438",
  "status": "AWAITING_PAYMENT",
  "source": "GHS",
  "destination": "NGN",
  "amount": 5.17301038,
  "totalSourceAmount": 5.17301038,
  "fee": 0.17301038,
  "totalDestinationAmount": 578.0,
  "mode": "test",
  "metadata": {
    "mobileMoneyPayIn": {
      "provider": "mtn",
      "providerName": "MTN",
      "phoneNumber": "0244123456",
      "attemptReference": "ref-02ec23bc404c4fa1842b01509be7a08f",
      "authorizationMode": "otp",
      "status": "inProgress",
      "message": "Please enter the one time password sent to your phone.",
      "expiresAt": "2026-09-22T08:27:59.881464Z"
    }
  },
  "ttl": 3599
}

Now the quote is AWAITING_PAYMENT, mobileMoneyPayIn has appeared, and ttl is 3599 — the countdown starts here, not at pricing.

Mobile money on dev is GHS only, and provider codes are lowercase — mtn, airtel, telecel.

Step 3: Authorize with the OTP

curl -X PUT https://api.hyperrails.io/exchange/api/v1/partners/marketplace/quote/QUOTE_ID/payment/authorize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "654321" }'

The full quote comes back. What changes is the message:

{
  "status": "AWAITING_PAYMENT",
  "metadata": {
    "mobileMoneyPayIn": {
      "status": "inProgress",
      "message": "Please complete the payment on your mtn line.",
      "authorizationMode": "otp"
    }
  }
}

The code was accepted. The money has not arrived yet.

Step 4: Poll until the payment settles

curl https://api.hyperrails.io/exchange/api/v1/partners/marketplace/quote/QUOTE_ID/payment/status \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

{
  "quoteId": "806dc37d-7880-4c8a-b871-c81e48a47438",
  "status": "AWAITING_PAYMENT",
  "totalDestinationAmount": 578.0,
  "metadata": {
    "mobileMoneyPayIn": {
      "attemptReference": "ref-02ec23bc404c4fa1842b01509be7a08f",
      "status": "successful",
      "message": "Payment completed successfully."
    }
  },
  "ttl": 3593
}

Watch metadata.mobileMoneyPayIn.status, not the top-level status. The payment reads successful while the quote is still AWAITING_PAYMENT — that is correct, not a stuck trade. The top-level status only changes when you complete.

In test mode this settled within about four seconds. Poll every few seconds rather than in a tight loop, and give up against ttl rather than a fixed number of tries.

Step 5: Complete the trade

curl -X PUT https://api.hyperrails.io/exchange/api/v1/partners/marketplace/quote/QUOTE_ID/complete \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

{
  "quoteId": "806dc37d-7880-4c8a-b871-c81e48a47438",
  "status": "SUCCESSFUL",
  "source": "GHS",
  "destination": "NGN",
  "amount": 5.17301038,
  "totalSourceAmount": 5.17301038,
  "fee": 0.17301038,
  "totalDestinationAmount": 578.0,
  "mode": "test",
  "allocationResult": {
    "allocations": [
      {
        "allocatedAmount": 578.00000208,
        "rate": 115.6,
        "reference": "HPR-ALO-1bbe8b80e32e42578b6aeb14f9276ada",
        "sourceAmount": 5.0
      }
    ],
    "totalDestinationAmount": 578.0,
    "weightedAverageRate": 115.6
  },
  "metadata": {
    "mobileMoneyPayIn": {
      "status": "successful",
      "message": "Payment completed successfully."
    },
    "transactionFee": {
      "feeType": "flat",
      "currency": "NGN",
      "flatFee": 20.0,
      "calculatedFee": 20.0
    }
  },
  "ttl": 0
}

status is SUCCESSFUL and ttl is 0. Done.

Confirming the money moved

Reading the NGN balance before and after:

NGN 5000126654.75  ->  5000127232.75   +578.00

Exactly totalDestinationAmount.

The source balance does not move. GHS was unchanged across the trade. The buyer paid by mobile money, so the source side never touches your GHS balance — only the destination is credited. Do not reconcile by expecting a matching debit.

Completing twice is safe. Calling complete a second time returned 200 with SUCCESSFUL again and the balance stayed at 5000127232.75 — no double credit. A retry after a network timeout is a safe no-op.

The provider’s liquidity drops by what you took. The NGN/GHS listing went from 768.27 to 190.27 — the 578.00 this trade consumed. That is the clearest independent confirmation the trade really settled.

When things go wrong

What you see	What it means	What to do
403 `requires [SECRET_KEY]`	You used a dashboard token	Use your secret key
400 `Unable to fulfill requested volume`	Bigger than the provider holds	Check listings; trade smaller
400 `No providers available`	Nobody trades that pair	Pick a listed pair
Quote is `PENDING`, no `mobileMoneyPayIn`	You passed `payment` to the express call	Call accept — express does not charge
401 with an empty body on accept	`express` left in the path	Accept is on `/quote/{id}/accept`, without `express`
400 on authorize	Wrong or expired OTP	Have the buyer request a new code
`payIn` stuck on `inProgress`	Buyer has not approved on their phone	Wait, watching `ttl`
400 on complete	Payment has not settled	Poll until `mobileMoneyPayIn.status` is `successful`
Duplicate quotes after a retry	`externalReference` is not idempotent	Track `quoteId`; cancel abandoned quotes
Source balance unchanged	Expected — mobile money pay-in	Reconcile the destination only

What to do next

Let a Buyer Pay for a Trade — the intent flow, with a ttl to show a customer
Find a Liquidity Provider — size a trade before you quote
Read Your Balances — confirm the trade landed

Core Concepts

Supported Currencies

Testing

Guides

Features

Webhooks

Expert Desk

What you’ll need

Express vs. the intent flow

Step 1: Create the express quote

Step 2: Accept the quote and charge the buyer

Step 3: Authorize with the OTP

Step 4: Poll until the payment settles

Step 5: Complete the trade

Confirming the money moved

When things go wrong

What to do next

​What you’ll need

​Express vs. the intent flow

​Step 1: Create the express quote

​Step 2: Accept the quote and charge the buyer

​Step 3: Authorize with the OTP

​Step 4: Poll until the payment settles

​Step 5: Complete the trade

​Confirming the money moved

​When things go wrong

​What to do next

What you’ll need

Express vs. the intent flow

Step 1: Create the express quote

Step 2: Accept the quote and charge the buyer

Step 3: Authorize with the OTP

Step 4: Poll until the payment settles

Step 5: Complete the trade

Confirming the money moved

When things go wrong

What to do next