Skip to navigation
API ReferenceOffers and Breakdowns

Find the best offer

Find the best offer.

Credential: Customer session

Before you call

  • A customer session for the same partner, integration, customer, wallet and chain.
  • An active saved account matching the catalog payment method.
  • A registered customer wallet and supported chain.

Finds merchant offers that match a customer’s BUY or SELL request.

amount.mode sets what amount.value means. With USDT, it is an exact token quantity. With FIAT, it is the market value of the tokens in fiatCurrencyId, before merchant margin and fees, for both BUY and SELL. Sinbad converts it to USDT using the current fiat/USD and USDT/USD rates, rounded down to six decimals. The final fiat payment includes merchant pricing and fees, so it can differ from the amount you entered.

paymentMethodId is required. On a SELL, set savedPaymentMethodId to choose the receiving account. If you omit it, Sinbad selects the customer’s first active matching account.

The response contains one instant offer or up to three alternatives. If the amount is outside every listing’s limits, or no inventory is eligible, the response is 200 with empty results. Sinbad excludes the customer’s own merchant wallet, ignoring case. If that is the only otherwise eligible match, the call returns 400 VALIDATION_ERROR with details.reason: SELF_TRADE_NOT_ALLOWED.

To create a breakdown, send the chosen offer’s breakdownInput unchanged. A new FIAT search returns a fixed USDT amount in breakdownInput, so the token quantity stays the same through checkout and across alternative currencies. A closest-amount suggestion can change that quantity.

Offer searches and breakdown creation share a limit of 60 requests per minute for each customer and integration. A 429 response includes Retry-After. Sinbad rechecks the price, listing availability and fees when you create the breakdown. You are responsible for verifying your customers’ identity. Location enforcement depends on the environment, so confirm the enabled policy with Sinbad.

Confirm with Sinbad that this endpoint is enabled in your environment.

Errors

StatusCodeWhat to do
400VALIDATION_ERRORCorrect the fields reported in details before retrying.
401UNAUTHENTICATEDCreate a new customer session or use a valid server credential.
403FORBIDDENCheck credential ownership, integration and the supplied Origin.
409CONFLICTRead the current state again before you prepare or retry.
429RATE_LIMITEDWait for Retry-After before retrying.
503UPSTREAM_ERRORRetry with backoff; preserve the same idempotency key for a repeated mutation.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
tokenSymbolenumRequired
Allowed values:
fiatCurrencyIdstringRequired
paymentMethodIdstringRequired
Required catalog method owned by the customer through an active saved account.
amountobjectRequired

FIAT is the principal’s market value in fiatCurrencyId before merchant margin and fees; USDT is an exact token quantity. FIAT conversion rounds down to six USDT decimals.

sideenumOptional
Customer action.
Allowed values:
typeenumOptional

Alias for customer side; conflicting aliases are rejected.

Allowed values:
displayCalculationModeenumOptionalDefaults to DUMMY

Card/Sheet display only. DUMMY uses a $10 USD example; REAL uses the actual requested or suggested amount. Execution always uses actual pricing. Preserve in issued breakdownInput.

Allowed values:
scheduled_atstringOptional

Optional ISO 8601 date-time, formatted YYYY-MM-DDTHH:mm[:ss[.SSS]][Z|±HH:MM]. Fractional seconds accept at most 3 digits, so truncate 6-digit values such as .190505 to milliseconds. An offset-free value uses timezone, or UTC if timezone is omitted. A value with Z or an explicit offset keeps that offset and ignores timezone. Normalized to UTC in breakdownInput. Filters merchant hours only; does not delay execution. Malformed, invalid or ambiguous local times (such as during a daylight saving change) are rejected with VALIDATION_ERROR.

timezonestringOptional

Optional IANA timezone name such as Asia/Karachi. Used only for an offset-free scheduled_at and ignored when scheduled_at has Z or an offset. Merchant hours use the merchant timezone at the scheduled instant.

savedPaymentMethodIdstringOptional
minRatingPercentdoubleOptional0-100

Optional minimum merchant rating; unrated merchants do not match.

minTradeCountintegerOptional0-9007199254740991
Optional minimum recorded merchant trade count.
ignoreMerchantOnlinebooleanOptionalDefaults to false
Include offline merchants. Preserve this value when creating a breakdown.
ignoreTradingHoursbooleanOptionalDefaults to false

Skip only supplied scheduled-hours filtering, including for alternatives. Preserve this value when creating a breakdown.

Response

One customer-scoped round-robin match or up to three alternatives; empty arrays mean no inventory.

instantlist of objects
alternativeslist of objects
paymentMethodobject or map from strings to any

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error