CRISPDocs
Dashboard
CRISP partnersEndpoint reference

Place order

POST /v1/accounts/{externalUserId}/orders

Submit one persisted order intent. Market BUY amount is cash; market SELL amount is shares. Limit orders use price and size. Prefer the SDK marketBuy, marketSell or limitOrder helpers for automatic execution-cell routing. A command being accepted is not proof of a fill.

Markets and trading guide · All endpoints · SDK: placeOrder, marketBuy, marketSell, limitOrder, submitOrder

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: Required — persist one key per intent. 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

FieldType / presenceDescription and constraints
externalUserIdstring
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

None.

Header parameters

FieldType / presenceDescription and constraints
Idempotency-Keystring
Required
Non-null
Validation pattern^[A-Za-z0-9._:-]{8,200}$

JSON body

Market BUY amount is a cash budget; market SELL amount is shares. Limit requires price and size. priceLimit is optional market slippage protection. Legacy numeric monetary inputs are accepted by the API; new clients use decimal strings.

Exactly one variant must match.

market · object
FieldType / presenceDescription and constraints
marketIdstring
Required
Non-null
—
tokenIdstring
Required
Non-null

Outcome token identifier. Keep as a string to avoid integer precision loss.

Validation pattern^(0|[1-9]\d{0,100})$
sidestring
Required
Non-null
Allowed: "BUY", "SELL"
typestring
Required
Non-null
Allowed: "market"
amountstring
Required
Non-null

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

Validation pattern^(?=\d+(?:\.\d+)?$)(?=.*[1-9]).+$
pricestring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
sizestring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
priceLimitstring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
orderTypestring
Optional
Non-null
—
expiresInSecondsinteger
Optional
Non-null
minimum: 0
outcomeIndexinteger
Optional
Non-null
minimum: 0
tickSizestring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
negRiskboolean
Optional
Non-null
—

Additional fields are not allowed in this object.

limit · object
FieldType / presenceDescription and constraints
marketIdstring
Required
Non-null
—
tokenIdstring
Required
Non-null

Outcome token identifier. Keep as a string to avoid integer precision loss.

Validation pattern^(0|[1-9]\d{0,100})$
sidestring
Required
Non-null
Allowed: "BUY", "SELL"
typestring
Required
Non-null
Allowed: "limit"
amountstring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
pricestring
Required
Non-null

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

Validation pattern^0?\.(?=\d*[1-9])\d+$
sizestring
Required
Non-null

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

Validation pattern^(?=\d+(?:\.\d+)?$)(?=.*[1-9]).+$
priceLimitstring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
orderTypestring
Optional
Non-null
—
expiresInSecondsinteger
Optional
Non-null
minimum: 0
outcomeIndexinteger
Optional
Non-null
minimum: 0
tickSizestring
Optional
Non-null

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

Validation pattern^\d+(?:\.\d+)?$
negRiskboolean
Optional
Non-null
—

Additional fields are not allowed in this object.

Request example

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.

POST /v1/accounts/user-123/orders
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>
Idempotency-Key: persisted-intent-0001
Content-Type: application/json

{
  "marketId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "tokenId": "12345678901234567890",
  "side": "BUY",
  "type": "market",
  "amount": "2.00"
}
Alternative request: limit
POST /v1/accounts/user-123/orders
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>
Idempotency-Key: persisted-intent-0001
Content-Type: application/json

{
  "marketId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "tokenId": "12345678901234567890",
  "side": "BUY",
  "type": "limit",
  "price": "0.40",
  "size": "5.00"
}

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.

202 · Accepted; inspect lifecycle state. This is not proof of a fill or payout.

Accepted for processing, not proof of a fill, completed provisioning or settled payout. Inspect resource state and follow the recovery guide.

Data payload

FieldType / presenceDescription and constraints
crispAccountIdstring
Required
Non-null

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

Format: uuid
externalUserIdstring
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}$
commandobject
Required
Non-null
Expand the structure below.
command: expand fields
FieldType / presenceDescription and constraints
idstring
Required
Non-null
Format: uuid
statestring
Required
Non-null
Allowed: "queued", "running", "retryable", "succeeded", "failed", "ambiguous"
failureCodestring | null
Required
Nullable
Expand the structure below.
failureCode: expand fields

string

Additional fields are not allowed in this object.

orderobject
Required
Non-null
Expand the structure below.
order: expand fields
FieldType / presenceDescription and constraints
idstring | null
Required
Nullable
Expand the structure below.
id: expand fields

string

marketIdstring
Required
Non-null
—
tokenIdstring
Required
Non-null

Outcome token identifier. Keep as a string to avoid integer precision loss.

sidestring
Required
Non-null
—
typestring
Required
Non-null
—
statusstring
Required
Non-null
—
fillobject | null
Required
Nullable
Expand the structure below.
fill: expand fields

Venue-owned JSON extension; fields are not a stable CRISP contract. Handle missing fields.

priceLimitstring | number | null
Required
Nullable
Expand the structure below.
priceLimit: expand variants

Any listed variant may match.

Variant 1 · string

string

Variant 2 · number

number

Additional fields are not allowed in this object.

Additional fields are not allowed in this object.

Full HTTP envelope
FieldType / presenceDescription and constraints
dataobject
Required
Non-null
Expand the structure below.
data: expand fields
FieldType / presenceDescription and constraints
crispAccountIdstring
Required
Non-null

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

Format: uuid
externalUserIdstring
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}$
commandobject
Required
Non-null
Expand the structure below.
command: expand fields
FieldType / presenceDescription and constraints
idstring
Required
Non-null
Format: uuid
statestring
Required
Non-null
Allowed: "queued", "running", "retryable", "succeeded", "failed", "ambiguous"
failureCodestring | null
Required
Nullable
Expand the structure below.
failureCode: expand fields

string

Additional fields are not allowed in this object.

orderobject
Required
Non-null
Expand the structure below.
order: expand fields
FieldType / presenceDescription and constraints
idstring | null
Required
Nullable
Expand the structure below.
id: expand fields

string

marketIdstring
Required
Non-null
—
tokenIdstring
Required
Non-null

Outcome token identifier. Keep as a string to avoid integer precision loss.

sidestring
Required
Non-null
—
typestring
Required
Non-null
—
statusstring
Required
Non-null
—
fillobject | null
Required
Nullable
Expand the structure below.
fill: expand fields

Venue-owned JSON extension; fields are not a stable CRISP contract. Handle missing fields.

priceLimitstring | number | null
Required
Nullable
Expand the structure below.
priceLimit: expand variants

Any listed variant may match.

Variant 1 · string

string

Variant 2 · number

number

Additional fields are not allowed in this object.

Additional fields are not allowed in this object.

requestIdstring
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.

202 response JSON
{
  "data": {
    "crispAccountId": "11111111-1111-4111-8111-111111111111",
    "externalUserId": "user-123",
    "command": {
      "id": "11111111-1111-4111-8111-111111111111",
      "state": "queued",
      "failureCode": null
    },
    "order": {
      "id": null,
      "marketId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "tokenId": "12345678901234567890",
      "side": "example",
      "type": "example",
      "status": "example",
      "fill": null,
      "priceLimit": null
    }
  },
  "requestId": "example-request-id"
}

Errors and recovery

StatusMeaning
400Inspect error.code and retain the original financial intent.
401Inspect error.code and retain the original financial intent.
403Inspect error.code and retain the original financial intent.
404Not visible for this account. A recovery lookup miss is not proof that an in-flight submission failed.
409Inspect error.code and retain the original financial intent.
429Inspect error.code and retain the original financial intent.
500Inspect error.code and retain the original financial intent.
502Inspect error.code and retain the original financial intent.
503Inspect 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
FieldType / presenceDescription and constraints
errorobject
Required
Non-null
Expand the structure below.
error: expand fields
FieldType / presenceDescription and constraints
codestring
Required
Non-null
—
messagestring
Required
Non-null
—
requestIdstring
Required
Non-null

Request correlation ID for debugging and support.

Additional fields are not allowed in this object.

Additional fields are not allowed in this object.

Raw contract

OpenAPI download · Advanced schema and legacy anchor

CRISP Partner Documentation

Create order cell capability

POST /v1/accounts/{externalUserId}/order-cell-capability

List orders

GET /v1/accounts/{externalUserId}/orders

On this page

AuthenticationRequest fieldsRequest exampleResponse fieldsResponse exampleErrors and recoveryRaw contract