Quotes and routing

Every session and payout is executed by exactly one gateway. When you omit gateway, OmiCloud chooses. POST /v1/quotes shows you that choice — and the alternatives — before you commit.

What routing considers

For a given request OmiCloud first finds the eligible gateways: connected to your account, enabled for the direction, supporting the currency / network / payment method, within limits, and not paused. Then it scores each one:

Input	Weight	Source
Fee on this route	high	the gateway's fee schedule for your account
Approval rate, last 30 days	high	this gateway's settled ÷ (settled + declined) on this route, across the OmiCloud network
Previously used by this end user	tie-breaker up	your `endUserId` has settled on this gateway before
Recent failures	tie-breaker down	gateway errors in the last few minutes

OmiCloud's own margin is not an input. Routing optimises for your cost and your conversion, not for OmiCloud's take.

The highest score wins. Ties go to the gateway with more recent successful volume.

Reading a quote

curl -X POST https://api.omicloud.io/v1/quotes \
  -H "Authorization: Bearer omi_live_…" \
  -H "Content-Type: application/json" \
  -d '{"direction":"deposit","amount":"100","currency":"USDT","network":"TRX","country":"PH","endUserId":"player-8812"}'

{
  "requestId": "req_01j6y9d4x2m8",
  "expiresAt": "2026-09-02T10:15:00Z",
  "quotes": [
    {
      "gateway": "dce",
      "paymentMethod": "USDT_TRC20",
      "sourceAmount": "100",
      "sourceCurrency": "USDT",
      "destinationAmount": "99.20",
      "destinationCurrency": "USDT",
      "exchangeRate": "1",
      "fees": { "gateway": "0.80", "network": "0", "total": "0.80" },
      "routing": { "score": 0.71, "rank": 1, "approvalRate30d": 0.94, "previouslyUsed": true }
    }
  ]
}

quotes is ordered by routing.rank. Rank 1 is what OmiCloud would pick if you created the session now without gateway.
destinationAmount is what arrives after fees.total. Show this to the end user.
exchangeRate is "1" for like-for-like (USDT → USDT). When fiat rails arrive it will carry the conversion.
expiresAt — quotes are indicative. Fees on a route rarely change, but network fees can. Refresh after expiry.

Quotes have no id and no lock in this version. Creating a session with the same parameters and the quoted gateway gets you the quoted fee unless the route changed in between — which is why expiresAt is short.

Three ways to use quotes

Don't. Omit gateway on sessions and payouts and let OmiCloud route. This is right for most integrations — you get the scoring for free and nothing to maintain when a gateway is added.

Show the winner. Call quotes to display "you will receive 99.20 USDT" before the end user commits, then create the session without gateway. If the route changed in the few seconds between, the session response says which gateway was used and the transaction has exact fees.

Let the end user choose. Display every quote and pass the chosen gateway on the session. Useful when gateways differ in something the end user cares about — a familiar brand, a wallet they already have. Follow the ranking when you lay them out: put rank 1 first and badge previouslyUsed. Familiarity converts better than a marginally lower fee.

Restricting routing

gateways: ["dce", "…"] on a quote or gateway: "dce" on a session limits the eligible set. Reasons to do it:

a gateway is misbehaving and you want it out for an hour,
you are ramping a new gateway on a percentage of traffic,
contractual volume commitments.

Nothing you send can route to a gateway you are not connected to.

Cascading

If the winning gateway rejects the submission (GATEWAY_ERROR at creation time), and you did not force gateway, OmiCloud tries the next-ranked eligible gateway before giving up. The transaction's events log records each attempt with source: system. You only see the final result. Cascading never happens after a gateway has accepted — a payout in processing is never re-sent elsewhere.