Create account
POST /v1/accounts
Provision an account using your authenticated user's stable external ID. Optionally include identity and referrerExternalUserId in the same request. Wait for ready before trading; acceptance does not mean provisioning is complete.
Accounts and identity guide · All endpoints · SDK: createAccount
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
None.
Query parameters
None.
Header parameters
| Field | Type / presence | Description and constraints |
|---|---|---|
Idempotency-Key | stringRequired Non-null | Validation pattern^[A-Za-z0-9._:-]{8,200}$ |
JSON body
| Field | Type / presence | Description and constraints | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
externalUserId | stringRequired 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}$ | |||||||||
email | stringOptional Non-null | Format: email maxLength: 254 | |||||||||
externalWalletAddress | stringOptional Non-null | Validation pattern^0x[0-9a-fA-F]{40}$ | |||||||||
externalIdentity | objectOptional Non-null | Expand the structure below. | |||||||||
externalIdentity: expand fields
Additional fields are not allowed in this object. | |||||||||||
referrerExternalUserId | stringOptional Non-null | The upline user's external ID within the same partner. Validation pattern^[A-Za-z0-9._:@-]{1,200}$ | |||||||||
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
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
{
"externalUserId": "user-123"
}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
| Field | Type / presence | Description and constraints |
|---|---|---|
crispAccountId | stringRequired Non-null | CRISP's account identifier; distinct from your external user ID. Format: uuid |
externalUserId | stringRequired 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}$ |
status | stringRequired Non-null | identity_pending is a legacy read state, not a supported new onboarding flow. Allowed: "provisioning", "wallet_pending", "polymarket_pending", "identity_pending", "ready", "failed", "revoked" |
failureCode | string | nullRequired Nullable | Expand the structure below. |
failureCode: expand fieldsstring | ||
createdAt | stringRequired Non-null | Format: date-time |
updatedAt | stringRequired Non-null | Format: date-time |
Additional fields are not allowed in this object.
Full HTTP envelope
| Field | Type / presence | Description and constraints | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | objectRequired Non-null | Expand the structure below. | ||||||||||||||||||||||||
data: expand fields
Additional fields are not allowed in this object. | ||||||||||||||||||||||||||
requestId | stringRequired 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",
"status": "provisioning",
"failureCode": null,
"createdAt": "2026-09-01T00:00:00Z",
"updatedAt": "2026-09-01T00:00:00Z"
},
"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 | objectRequired Non-null | Expand the structure below. | ||||||||||||
error: expand fields
Additional fields are not allowed in this object. | ||||||||||||||
Additional fields are not allowed in this object.