payments/pkg/client/docs/models/components/v3order.md

V3Order

A trade order submitted to an exchange-style PSP. Orders are read-only in the Formance API: they are fetched from the underlying connector. Status transitions are captured via the adjustments array; each adjustment is a point-in-time snapshot from the PSP.

Fields

Field	Type	Required	Description
ID	string	✔️	Formance-assigned unique order ID (composed from the PSP reference and connector ID).
ConnectorID	string	✔️	ID of the Formance connector this order was fetched from.
Provider	string	✔️	Provider name of the connector (e.g. coinbaseprime).
Reference	string	✔️	PSP-assigned order reference. Unique within the connector; used as the storage dedup key.
ClientOrderID	*string	➖	Client-assigned ID supplied to the PSP for placement idempotency (e.g. Coinbase client_order_id, Kraken cl_ord_id, Binance clientOrderId). Stored for traceability only — Formance does NOT dedup on this field.
CreatedAt	time.Time	✔️	When the order was created on the PSP.
UpdatedAt	time.Time	✔️	When Formance last observed a state change on the order. Equivalent to the latest adjustment's createdAt.
Direction	components.V3OrderDirectionEnum	✔️	Whether an order buys or sells the base asset.
SourceAsset	string	✔️	Asset being spent, in SYMBOL/precision form (e.g. USD/2, BTC/8). For BUY: the quote currency. For SELL: the base currency.
DestinationAsset	string	✔️	Asset being received, in SYMBOL/precision form. For BUY: the base currency. For SELL: the quote currency.
Type	components.V3OrderTypeEnum	✔️	Exchange order type. Determines which price fields are meaningful on V3Order: LIMIT-family types use limitPrice; STOP-family types use stopPrice; TWAP/VWAP are time-weighted execution algorithms.
Status	components.V3OrderStatusEnum	✔️	Lifecycle of an order on the exchange. PENDING — accepted by the exchange, not yet working. OPEN — live on the book, no fills yet. PARTIALLY_FILLED — live on the book, some base quantity filled. FILLED — fully filled, terminal. CANCELLED — cancelled by the user or system, terminal. FAILED — rejected by the exchange, terminal. See error for details. EXPIRED — timeInForce elapsed before full fill, terminal.
BaseQuantityOrdered	*big.Int	✔️	Amount of base asset the order was placed for, as an integer at the base asset's precision.
BaseQuantityFilled	*big.Int	➖	Amount of base asset filled so far, as an integer at the base asset's precision. Null before any fill.
LimitPrice	*big.Int	➖	Maximum price (for BUY) or minimum price (for SELL) at which the order may execute, in priceAsset precision. Required for LIMIT-family order types; null otherwise.
StopPrice	*big.Int	➖	Trigger price at which a STOP / STOP_LIMIT order activates, in priceAsset precision. Null for non-stop order types.
TimeInForce	components.V3TimeInForceEnum	✔️	How long an order is valid on the exchange. GOOD_UNTIL_CANCELLED — rests until explicitly cancelled. GOOD_UNTIL_DATE_TIME — rests until expiresAt. IMMEDIATE_OR_CANCEL — fill immediately, cancel any unfilled portion. FILL_OR_KILL — fill fully and immediately, or cancel entirely.
ExpiresAt	*time.Time	➖	Expiration instant for GOOD_UNTIL_DATE_TIME orders. Null for other time-in-force values.
Fee	*big.Int	➖	Commission charged by the PSP for the order, as an integer in feeAsset precision.
FeeAsset	*string	➖	Currency the fee is denominated in, in SYMBOL/precision form. Typically the quote asset.
AverageFillPrice	*big.Int	➖	Volume-weighted average price across all fills so far, in priceAsset precision. Analytics field — may be absent if the PSP does not report it.
QuoteAmount	*big.Int	➖	Total amount of quote currency exchanged so far, as reported by the PSP (e.g. Coinbase filled_value), at quoteAsset precision. For BUY: amount spent. For SELL: amount received.
QuoteAsset	*string	➖	Quote currency with precision (e.g. USD/2). Null when the order has no quote-side amounts reported yet.
PriceAsset	*string	➖	Currency + precision under which limitPrice, stopPrice, and averageFillPrice should be interpreted. Separate from quoteAsset because some PSPs return price strings with more decimal digits than the quote currency's natural precision.
SourceAccountID	*string	➖	Formance account ID of the wallet the source asset was debited from. Null if the PSP did not return enough information to resolve it at ingestion time.
DestinationAccountID	*string	➖	Formance account ID of the wallet the destination asset was credited to. Null if unresolvable.
Metadata	map[string]string	➖	N/A
Adjustments	[]components.V3OrderAdjustment	➖	Ordered history of state snapshots for this order. The most recent element reflects the current status.
Error	*string	➖	Human-readable error from the PSP (e.g. rejection reason) when status is FAILED. Null otherwise.