Skip to main content
GET
curl
The response body shown here is a static example, not live data. After you click Send, your live result appears in a separate panel headed 200 OK. The panel under the status-code tabs is a fixed sample from the spec — its field values (fees, prices, sizes, IDs, timestamps) are placeholders. Use Send, or call the endpoint, for current values.
Returns the single fill belonging to the requested account for the given trade ID. Requires the address query parameter (optional accountIndex selects a subaccount, default 0): fill data is partitioned by account, so the lookup needs the owning account. A trade can produce one fill per participant that share a tradeId; this returns the leg owned by the requested account. No authentication header is required.

Path Parameters

tradeId
string
required

Trade identifier of the fill (the tradeId field returned by GET /v1/fills). A non-integer value → 400.

Example:

"12345"

Query Parameters

address
string
required

Master Ethereum address for this API key (must match address from POST /createApiKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase af after 0x.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$
accountIndex
integer
default:0

Subaccount index (0–9) to scope the request to. Defaults to 0 (the primary account). Values above 9 → 400.

Required range: 0 <= x <= 9

Response

Fill details.

Unified fill shape used across REST responses, WebSocket snapshots, and streaming updates. Fields only available from the store are optional and may be absent in streaming updates.

tradeId
string
required

Unique trade identifier.

Example:

"12345"

orderId
string
required

Order ID that generated this fill.

Example:

"order-abc-123"

marketId
integer
required

Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.

Required range: 0 <= x <= 65535
marketDisplayName
string
required

Market symbol (e.g. BTC-USD).

Example:

"BTC-USD"

side
enum<string>
required

Order side.

Available options:
BUY,
SELL
originalSize
string
required

Original order size in human-readable base-asset units (decimal string).

Example:

"1.0"

size
string
required

Fill size in human-readable base-asset units (decimal string).

Example:

"0.01"

price
string
required

Fill price in human-readable USD (decimal string).

Example:

"50000.5"

fee
string
required

Fee amount (decimal string). On the liquidated leg of an engine liquidation this is the liquidation penalty (the market's liquidation fee rate applied to the fill notional, paid to the insurance fund) — "0" when the market has no liquidation fee configured. ADL legs carry no fee.

Example:

"0.5"

role
enum<string>
required

Liquidity role (maker or taker).

Available options:
MAKER,
TAKER
createdAt
integer<int64>
required

Fill timestamp (epoch microseconds).

address
string

Ethereum address (lowercase 0x + 40 hex). Only present on REST and snapshot responses.

Example:

"0x0000000000000000000000000000000000000000"

accountIndex
integer

Account index (account index, 0–9). Identifies the account for orders, positions, fills, and API keys.

Required range: 0 <= x <= 9
clientId
string

Client-provided order ID. Only present on streaming updates.

closedPnl
string

Realized PnL for this fill (decimal string, quote currency): cost-basis release (old borrowedCapital − new borrowedCapital − Δsize × price) minus the fill's fee. Opening and same-direction add legs contribute −fee (price PnL is 0). On a flat account, Σ closedPnl + Σ funding equals netQuoteBalance − net deposits. On the liquidated leg of a forced closure (liquidation.method == LIQUIDATION) the engine does not stamp realized PnL on the fill — closedPnl reads "0" by design; the realized loss is already reflected in the account's netQuoteBalance on the accompanying account update.

Example:

"12.34"

remainingSize
string

Remaining unfilled order size after this fill. Only present on streaming updates.

positionEffect
enum<string>

How this fill affected the account's position in marketId. For taker fills the value is the net effect across all fills in the aggregated update (FLIP_* covers a position that closed and reopened on the opposite side within one user order). May be absent on persisted rows from before the field was introduced.

Available options:
OPEN_LONG,
OPEN_SHORT,
ADD_LONG,
ADD_SHORT,
CLOSE_LONG,
CLOSE_SHORT,
FLIP_LONG_TO_SHORT,
FLIP_SHORT_TO_LONG
sequenceNumber
integer<uint64>

Sequence number for ordering and reconciliation. Only present on streaming updates.

liquidation
object

Present only when this fill closed a position involuntarily — on the liquidated account's leg of an engine liquidation (LIQUIDATION) or the deleveraged counterparty's leg of an auto-deleverage (ADL). The voluntary counterparty leg of a liquidation match (a resting maker order that got hit) does not carry this marker. Absent on voluntary fills and on rows persisted before the marker was introduced. This field, not the order-ID format, is the supported way to detect forced closures (the engine's synthetic liq: order-ID prefix is an internal detail and not part of the API contract).