Quotes / API reference

Create a quote

Request and response reference for POST /v1/quotes.

POST/v1/quotes

Authentication: API key

Use the base URL and access configuration provided to your institution. Examples are request templates, not transaction results. Field tables focus on client fields; preserve additional metadata returned by the configured service.

Request

Keep API keys in your backend. Required entitlements and institution scope still apply.

Request templatecURL

curl -X POST "$OSAI_API_BASE_URL/v1/quotes" \
  -H "Authorization: ApiKey $OSAI_PUBLIC_ID:$OSAI_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <stable-operation-key>" \
  --data '{
  "quote_mode": "FIXED_SOURCE",
  "base_amount_minor": 100000,
  "base_currency": "NGN",
  "quote_currency": "USD",
  "customer_reference": "order-1042"
}'

Parameters

Name	Location	Requirement	Description
`Idempotency-Key`	header · string	Required	Use the value defined for this resource.
`X-Request-Id`	header · string	Optional	Use the value defined for this resource.
`Authorization`	header · string	Required	Use the value defined for this resource.

Request body

Send JSON with Content-Type: application/json. Nested field names identify their parent object; required markers apply within that object. Replace template values using the relevant resource and configured instrument rules.

Field	Type	Description & constraints
`base_amount_minor`Optional	`integer`	For FIXED_SOURCE, the exact all-in source debit including fees. Required only for FIXED_SOURCE.
`quote_mode`Optional	`string`	Omitted values retain the legacy FIXED_SOURCE request interpretation.Values: FIXED_SOURCE, FIXED_DESTINATION
`destination_amount_minor`Optional	`integer`	Exact target proceeds for FIXED_DESTINATION. Required only for FIXED_DESTINATION.
`base_currency`Required in parent object	`string`	Defined by the resource contract.
`quote_currency`Required in parent object	`string`	Defined by the resource contract.
`destination_rail`Optional	`string`	Defined by the resource contract.
`urgency`Optional	`string`	Defined by the resource contract.
`customer_reference`Optional	`string`	Institution-scoped reference returned on the resulting trade.

Responses

Inspect HTTP status before parsing a body. These tables describe client response fields rather than invented successful transaction payloads.

200 · Quote created

Field	Type	Description & constraints
`quote_id`Required in parent object	`string`	Defined by the resource contract.
`status`Required in parent object	`string`	Defined by the resource contract.
`base_amount_minor`Required in parent object	`integer`	Defined by the resource contract.
`base_currency`Required in parent object	`string`	Defined by the resource contract.
`quote_currency`Required in parent object	`string`	Defined by the resource contract.
`destination_rail`Optional	`string`	Defined by the resource contract.
`amount_out_minor`Required in parent object	`integer`	Defined by the resource contract.
`rate_minor`Required in parent object	`integer`	Defined by the resource contract.
`fee_minor`Required in parent object	`integer`	Institution pricing fee in source-currency minor units.
`quote_mode`Required in parent object	`string`	Defined by the resource contract.Values: FIXED_SOURCE, FIXED_DESTINATION
`source_principal_minor`Required in parent object	`integer`	Source-currency principal converted by the quoted rate.
`total_debit_minor`Required in parent object	`integer`	Exact all-in source-currency debit, including fee.
`total_cost_minor`Required in parent object	`integer`	Total customer debit in source-currency minor units, including applicable customer-paid fees; equal to total_debit_minor.
`total_cost_currency`Required in parent object	`string`	Currency of total_cost_minor; equal to base_currency.
`destination_target_minor`Optional	`integer`	Contracted destination amount for FIXED_DESTINATION; zero for FIXED_SOURCE.
`destination_surplus_minor`Required in parent object	`integer`	Conservatively rounded proceeds above the exact requested destination target; separately identified for downstream accounting.
`rate_direction`Required in parent object	`string`	Defined by the resource contract.
`rate_scale`Required in parent object	`integer`	Rate is destination major units per source major unit multiplied by this scale.
`fee_schedule_id`Required in parent object	`string`	Defined by the resource contract.
`fee_schedule_version`Required in parent object	`integer`	Defined by the resource contract.
`source_minor_exponent`Required in parent object	`integer`	Defined by the resource contract.
`destination_minor_exponent`Required in parent object	`integer`	Defined by the resource contract.
`sell_amount_minor`Required in parent object	`integer`	Defined by the resource contract.
`sell_currency`Required in parent object	`string`	Defined by the resource contract.
`buy_amount_minor`Required in parent object	`integer`	Defined by the resource contract.
`buy_currency`Required in parent object	`string`	Defined by the resource contract.
`expires_at`Required in parent object	`string`date-time	Defined by the resource contract.
`request_id`Optional	`string`	Defined by the resource contract.

400 · Validation failure

Field	Type	Description & constraints
`error`Required in parent object	`object`	Defined by the resource contract.
`error.code`Required in parent object	`string`	Defined by the resource contract.
`error.message`Required in parent object	`string`	Defined by the resource contract.
`error.request_id`Required in parent object	`string`	Defined by the resource contract.

Retries & recovery

Keep the original request identifiers and any required idempotency key. A timeout does not establish failure. Read the original resource or command before another financial write; use expected versions for concurrent changes.

Error handling →Idempotency →