Trades / API reference
List institution trades
Request and response reference for GET /v1/trades.
GET
/v1/tradesAuthentication: 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.
curl -X GET "$OSAI_API_BASE_URL/v1/trades" \
-H "Authorization: ApiKey $OSAI_PUBLIC_ID:$OSAI_API_SECRET"Parameters
| Name | Location | Requirement | Description |
|---|---|---|---|
Authorization | header · string | Required | Use the value defined for this resource. |
X-Request-Id | header · string | Optional | Use the value defined for this resource. |
page | query · integer | Optional | Use the value defined for this resource. |
page_size | query · integer | Optional | Use the value defined for this resource. |
from | query · string | Optional | Inclusive lower bound on trade creation time or terminal settlement time, according to the endpoint. |
to | query · string | Optional | Exclusive upper bound on trade creation time or terminal settlement time, according to the endpoint. |
currency | query · string | Optional | Exact currency filter; trade lists use sell/base currency and settlement reports use settlement currency. |
status | query · string | Optional | Exact canonical status for the endpoint's resource. |
customer_reference | query · string | Optional | Exact institution-scoped reference supplied when requesting the quote. |
Request body
This operation does not define a JSON request body.
Responses
Inspect HTTP status before parsing a body. These tables describe client response fields rather than invented successful transaction payloads.
200 · Trade page
| Field | Type | Description & constraints |
|---|---|---|
itemsRequired in parent object | array | Defined by the resource contract. |
items[].trade_idRequired in parent object | string | Defined by the resource contract. |
items[].quote_idRequired in parent object | string | Defined by the resource contract. |
items[].institution_idRequired in parent object | string | Defined by the resource contract. |
items[].statusRequired in parent object | string | Defined by the resource contract. |
items[].base_amount_minorOptional | integer | Defined by the resource contract. |
items[].base_currencyOptional | string | Defined by the resource contract. |
items[].quote_currencyOptional | string | Defined by the resource contract. |
items[].pricing_snapshotOptional | object | Immutable accepted quote economics; present when the trade was created from a priced quote. |
items[].pricing_snapshot.quote_modeRequired in parent object | string | Defined by the resource contract.Values: FIXED_SOURCE, FIXED_DESTINATION |
items[].pricing_snapshot.requested_amount_minorOptional | integer | Defined by the resource contract. |
items[].pricing_snapshot.source_principal_minorRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.fee_minorRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.total_debit_minorRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.destination_amount_minorRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.destination_target_minorOptional | integer | Defined by the resource contract. |
items[].pricing_snapshot.destination_surplus_minorOptional | integer | Defined by the resource contract. |
items[].pricing_snapshot.source_currencyRequired in parent object | string | Defined by the resource contract. |
items[].pricing_snapshot.destination_currencyRequired in parent object | string | Defined by the resource contract. |
items[].pricing_snapshot.rate_scaledRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.rate_directionRequired in parent object | string | Defined by the resource contract. |
items[].pricing_snapshot.rate_scaleRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.fee_schedule_idRequired in parent object | string | Defined by the resource contract. |
items[].pricing_snapshot.fee_schedule_versionRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.source_minor_exponentRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.destination_minor_exponentRequired in parent object | integer | Defined by the resource contract. |
items[].pricing_snapshot.expires_atRequired in parent object | string | Defined by the resource contract. |
items[].settlement_idOptional | string | Defined by the resource contract. |
items[].fx_executionOptional | object | FX execution state is separate from destination payout state; UNKNOWN requires reconciliation before another submission. |
items[].fx_execution.execution_idOptional | string | Defined by the resource contract. |
items[].fx_execution.executor_idOptional | string | Defined by the resource contract. |
items[].fx_execution.request_referenceOptional | string | Defined by the resource contract. |
items[].fx_execution.statusOptional | string | Defined by the resource contract.Values: READY, SUBMITTED, UNKNOWN, EXECUTED, FAILED |
items[].customer_referenceOptional | string | Institution-scoped client reference, when supplied. |
items[].request_idOptional | string | Defined by the resource contract. |
pageRequired in parent object | integer | Defined by the resource contract. |
page_sizeRequired in parent object | integer | Defined by the resource contract. |
totalRequired in parent object | integer | Defined by the resource contract. |
request_idRequired in parent object | string | Defined by the resource contract. |
400 · Validation failure
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | object | Defined by the resource contract. |
error.codeRequired in parent object | string | Defined by the resource contract. |
error.messageRequired in parent object | string | Defined by the resource contract. |
error.request_idRequired in parent object | string | Defined by the resource contract. |
503 · Trade read service unavailable
No client body fields are defined for this response.
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.