List trade fills

Read reconciled fills and fee allocation metadata within a timestamp window. This uses cursor pagination; continue using the returned cursor rather than treating one page as the complete history.

Markets and trading guide · All endpoints · SDK: listTradeFills, tradeFills

Authentication

Server-to-server HMAC. Your key selects the partner; your backend must authorize the end user.

CRISP enables access to the features agreed for your integration. Contact CRISP if an enabled feature returns an access error.

Idempotency-Key: Not required by this operation. Signing and authentication →

Request fields

Required means the field must be present. Nullable means an explicit JSON null is allowed; it does not mean optional.

Path parameters

Field	Type / presence	Description and constraints
`externalUserId`	`string` Required Non-null	Your stable user ID within the authenticated partner. Derive it from your authorized server session. Validation pattern `^[A-Za-z0-9._:@-]{1,200}$`

Query parameters

Field	Type / presence	Description and constraints
`from`	`string` Required Non-null	Format: date-time
`to`	`string` Required Non-null	Format: date-time
`limit`	`integer` Optional Non-null	Maximum number of records requested in one page. Default: 50 minimum: 1 maximum: 100
`cursor`	`string` Optional Non-null	Continuation cursor. Preserve and pass the returned value when requesting the next page.

Header parameters

No operation-specific headers. The HMAC headers above still apply.

JSON body

No request body.

Illustrative identifiers only: replace them with resources from your integration. Keep credentials on your backend. HTTP placeholders must be signed; the SDK signs automatically. Financial intent keys must be persisted and unique per new action.

GET /v1/accounts/user-123/trade-fills?from=2026-09-01T00%3A00%3A00Z&to=2026-09-02T00%3A00%3A00Z&limit=50
Host: partner-api.crisp.trade
X-Crisp-Partner-Key: <server-key-id>
X-Crisp-Timestamp: <fresh-ISO-8601-UTC-timestamp>
X-Crisp-Nonce: <fresh-unique-nonce>
X-Crisp-Signature: <computed-base64-HMAC>

Response fields

HTTP responses use the envelope below. SDK calls expose its payload as result.data, with HTTP status and request metadata on the SDK wrapper.

200 · Success

Data payload

Field Type / presence Description and constraints

crispAccountId

string

Required

Non-null

CRISP's account identifier; distinct from your external user ID.

Format: uuid

externalUserId

string

Required

Non-null

Your stable user ID within the authenticated partner. Derive it from your authorized server session.

Validation pattern

^[A-Za-z0-9._:@-]{1,200}$

window

object

Required

Non-null

Expand the structure below.

window: expand fields

Field	Type / presence	Description and constraints
`from`	`string` Required Non-null	Format: date-time
`to`	`string` Required Non-null	Format: date-time

Additional fields are not allowed in this object.

fills

array<object>

Required

Non-null

Expand the structure below.

fills: expand item fields

Field Type / presence Description and constraints

id

string

Required

Non-null

Format: uuid

venue

string

Required

Non-null

—

upstreamFillId

string

Required

Non-null

—

clobOrderId

string | null

Required

Nullable

Expand the structure below.

clobOrderId: expand fields

string

clientOrderId

string | null

Required

Nullable

Expand the structure below.

clientOrderId: expand fields

string

matchedAt

string

Required

Non-null

Format: date-time

marketId

string | null

Required

Nullable

Expand the structure below.

marketId: expand fields

string

marketTitle

string | null

Required

Nullable

Expand the structure below.

marketTitle: expand fields

string

assetId

string | null

Required

Nullable

Expand the structure below.

assetId: expand fields

string

outcome

string | null

Required

Nullable

Expand the structure below.

outcome: expand fields

string

side

string | null

Required

Nullable

Expand the structure below.

side: expand fields

string

price

string | null

Required

Nullable

Expand the structure below.

price: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

shares

string | null

Required

Nullable

Expand the structure below.

shares: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

notionalUsdc

string | null

Required

Nullable

Expand the structure below.

notionalUsdc: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

venueFeeUsdc

string | null

Required

Nullable

Expand the structure below.

venueFeeUsdc: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

venueTransactionHash

string | null

Required

Nullable

Expand the structure below.

venueTransactionHash: expand fields

string

venueStatus

string | null

Required

Nullable

Expand the structure below.

venueStatus: expand fields

string

fee

object | null

Required

Nullable

Expand the structure below.

fee: expand fields

Field Type / presence Description and constraints

collectionId

string

Required

Non-null

Format: uuid

amountUsdc

string

Required

Non-null

Exact decimal string. Never use floating point for ledger arithmetic.

Validation pattern

^\d+(?:\.\d+)?$

state

string

Required

Non-null

Allowed: "queued", "submitting", "submitted", "settled", "manual_review"

transactionHash

string | null

Required

Nullable

Expand the structure below.

transactionHash: expand fields

string

allocations

array<object>

Required

Non-null

Expand the structure below.

allocations: expand item fields

Field Type / presence Description and constraints

recipientType

string

Required

Non-null

Allowed: "crisp_revenue", "partner_treasury", "referral"

referralLevel

integer | null

Required

Nullable

Expand the structure below.

referralLevel: expand fields

integer

minimum: 0

beneficiaryAccountId

string | null

Required

Nullable

Expand the structure below.

beneficiaryAccountId: expand fields

string

Format: uuid

amountUsdc

string

Required

Non-null

Exact decimal string. Never use floating point for ledger arithmetic.

Validation pattern

^\d+(?:\.\d+)?$

destinationAddress

string | null

Required

Nullable

Expand the structure below.

destinationAddress: expand fields

string

payout

object | null

Required

Nullable

Expand the structure below.

payout: expand fields

Field	Type / presence	Description and constraints
`id`	`string` Required Non-null	Format: uuid
`state`	`string` Required Non-null	Allowed: "queued", "submitting", "submitted", "settled", "manual_review"
`batchAmountUsdc`	`string` Required Non-null	Exact decimal string. Never use floating point for ledger arithmetic. Validation pattern `^\d+(?:\.\d+)?$`
`transactionHash`	`string \| null` Required Nullable	Expand the structure below.
transactionHash: expand fields string

Additional fields are not allowed in this object.

cursor

string | null

Required

Nullable

Continuation cursor. Preserve and pass the returned value when requesting the next page.

cursor: expand fields

string

hasMore

boolean

Required

Non-null

Whether further pages remain in this result set.

Additional fields are not allowed in this object.

Full HTTP envelope

Field Type / presence Description and constraints

data

object

Required

Non-null

Expand the structure below.

data: expand fields

Field Type / presence Description and constraints

crispAccountId

string

Required

Non-null

CRISP's account identifier; distinct from your external user ID.

Format: uuid

externalUserId

string

Required

Non-null

Your stable user ID within the authenticated partner. Derive it from your authorized server session.

Validation pattern

^[A-Za-z0-9._:@-]{1,200}$

window

object

Required

Non-null

Expand the structure below.

window: expand fields

Field	Type / presence	Description and constraints
`from`	`string` Required Non-null	Format: date-time
`to`	`string` Required Non-null	Format: date-time

Additional fields are not allowed in this object.

fills

array<object>

Required

Non-null

Expand the structure below.

fills: expand item fields

Field Type / presence Description and constraints

id

string

Required

Non-null

Format: uuid

venue

string

Required

Non-null

—

upstreamFillId

string

Required

Non-null

—

clobOrderId

string | null

Required

Nullable

Expand the structure below.

clobOrderId: expand fields

string

clientOrderId

string | null

Required

Nullable

Expand the structure below.

clientOrderId: expand fields

string

matchedAt

string

Required

Non-null

Format: date-time

marketId

string | null

Required

Nullable

Expand the structure below.

marketId: expand fields

string

marketTitle

string | null

Required

Nullable

Expand the structure below.

marketTitle: expand fields

string

assetId

string | null

Required

Nullable

Expand the structure below.

assetId: expand fields

string

outcome

string | null

Required

Nullable

Expand the structure below.

outcome: expand fields

string

side

string | null

Required

Nullable

Expand the structure below.

side: expand fields

string

price

string | null

Required

Nullable

Expand the structure below.

price: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

shares

string | null

Required

Nullable

Expand the structure below.

shares: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

notionalUsdc

string | null

Required

Nullable

Expand the structure below.

notionalUsdc: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

venueFeeUsdc

string | null

Required

Nullable

Expand the structure below.

venueFeeUsdc: expand fields

Exact decimal string. Never use floating point for ledger arithmetic.

venueTransactionHash

string | null

Required

Nullable

Expand the structure below.

venueTransactionHash: expand fields

string

venueStatus

string | null

Required

Nullable

Expand the structure below.

venueStatus: expand fields

string

fee

object | null

Required

Nullable

Expand the structure below.

fee: expand fields

Field Type / presence Description and constraints

collectionId

string

Required

Non-null

Format: uuid

amountUsdc

string

Required

Non-null

Exact decimal string. Never use floating point for ledger arithmetic.

Validation pattern

^\d+(?:\.\d+)?$

state

string

Required

Non-null

Allowed: "queued", "submitting", "submitted", "settled", "manual_review"

transactionHash

string | null

Required

Nullable

Expand the structure below.

transactionHash: expand fields

string

allocations

array<object>

Required

Non-null

Expand the structure below.

allocations: expand item fields

Field Type / presence Description and constraints

recipientType

string

Required

Non-null

Allowed: "crisp_revenue", "partner_treasury", "referral"

referralLevel

integer | null

Required

Nullable

Expand the structure below.

referralLevel: expand fields

integer

minimum: 0

beneficiaryAccountId

string | null

Required

Nullable

Expand the structure below.

beneficiaryAccountId: expand fields

string

Format: uuid

amountUsdc

string

Required

Non-null

Exact decimal string. Never use floating point for ledger arithmetic.

Validation pattern

^\d+(?:\.\d+)?$

destinationAddress

string | null

Required

Nullable

Expand the structure below.

destinationAddress: expand fields

string

payout

object | null

Required

Nullable

Expand the structure below.

payout: expand fields

Field	Type / presence	Description and constraints
`id`	`string` Required Non-null	Format: uuid
`state`	`string` Required Non-null	Allowed: "queued", "submitting", "submitted", "settled", "manual_review"
`batchAmountUsdc`	`string` Required Non-null	Exact decimal string. Never use floating point for ledger arithmetic. Validation pattern `^\d+(?:\.\d+)?$`
`transactionHash`	`string \| null` Required Nullable	Expand the structure below.
transactionHash: expand fields string

Additional fields are not allowed in this object.

cursor

string | null

Required

Nullable

Continuation cursor. Preserve and pass the returned value when requesting the next page.

cursor: expand fields

string

hasMore

boolean

Required

Non-null

Whether further pages remain in this result set.

Additional fields are not allowed in this object.

requestId

string

Required

Non-null

Request correlation ID for debugging and support.

Additional fields are not allowed in this object.

Response example

Schema illustration, not live account data. Null means unavailable or not applicable, never an invented zero. Empty arrays do not imply the endpoint always returns no results.

200 response JSON

{
  "data": {
    "crispAccountId": "11111111-1111-4111-8111-111111111111",
    "externalUserId": "user-123",
    "window": {
      "from": "2026-09-01T00:00:00Z",
      "to": "2026-09-02T00:00:00Z"
    },
    "fills": [],
    "cursor": null,
    "hasMore": false
  },
  "requestId": "example-request-id"
}

Errors and recovery

Status	Meaning
`400`	Inspect error.code and retain the original financial intent.
`401`	Inspect error.code and retain the original financial intent.
`403`	Inspect error.code and retain the original financial intent.
`404`	Not visible for this account. A recovery lookup miss is not proof that an in-flight submission failed.
`409`	Inspect error.code and retain the original financial intent.
`429`	Inspect error.code and retain the original financial intent.
`500`	Inspect error.code and retain the original financial intent.
`502`	Inspect error.code and retain the original financial intent.
`503`	Inspect error.code and retain the original financial intent.

Inspect the error code and outcomeUnknown, not just the HTTP status. Preserve the original intent after financial uncertainty. Read-only retries should honor Retry-After. Recovery workflow →

Error response fields

Field Type / presence Description and constraints

error

object

Required

Non-null

Expand the structure below.

error: expand fields

Field	Type / presence	Description and constraints
`code`	`string` Required Non-null	—
`message`	`string` Required Non-null	—
`requestId`	`string` Required Non-null	Request correlation ID for debugging and support.

Additional fields are not allowed in this object.

Raw contract

OpenAPI download · Advanced schema and legacy anchor

Authentication

Request fields

Path parameters

Query parameters

Header parameters

JSON body

Request example

Response fields

200 · Success

Data payload

Response example

Errors and recovery

Raw contract

On this page