Concepts and lifecycle
Know what you own, what CRISP handles, and when an action is actually complete.
Terms used in these guides
CRISP calls an organization integrating its services a partner. These guides address you directly, using the following terms consistently:
| Term | Meaning |
|---|---|
| You / your organization | The business or team operating an integration with CRISP |
| Your application | The product you build, including its frontend and backend |
| Your backend | Your server code that authenticates users and calls CRISP |
| Your users | People using your application to trade |
| Your team | Staff with access to the Partner Dashboard; dashboard access is separate from a user's trading account |
| Managed trading account | A user's account provisioned through CRISP and registered under your organization's integration |
| Your API credentials | The API key ID and secret identifying your organization's integration and enabled features; they do not authenticate individual users |
| Your treasury | Your organization's allocation of trading fees; its payout wallet is separate from users' trading wallets |
| Website project | A website configured for traffic analytics, selected by projectSlug within your organization's integration |
| CRISP | The service providing managed accounts, execution and financial reconciliation |
| Venue | The underlying market and execution platform, currently Polymarket |
Partner API, Partner Dashboard and Partner SDK are CRISP product
names. API headers, fields and error codes retain their exact technical names,
including X-Crisp-Partner-Key. A technical reference to a tenant means the
organization scope identified by your API credentials. “Your account” is avoided
where it could mean either your organization's integration or a user's trading account.
Responsibilities
| Your application owns | CRISP owns | The SDK handles for your backend |
|---|---|---|
| User login, authorization and stable external IDs | Account mapping scoped to your organization and managed wallets | Typed requests and HMAC signing |
| Persisting the exact input and key for each financial intent | Durable commands, execution and reconciliation | Direct order routing and bounded same-intent fallback |
| User consent, deposits from an external wallet, and the UI | Managed execution, withdrawal processing and payout records | Read-only wait/recovery helpers |
| Authenticated resource loaders and rendering account state | Account-scoped updates and authoritative financial state | Account-sync store: event mapping, batched refresh, cursor storage, reconnect and resync |
The SDK does not authenticate your users, store your intents, submit an external-wallet deposit, or decide that an order filled just because HTTP succeeded. Keep your API credentials on your server. Forward only a scoped realtime session to the browser when using realtime.
The guides sometimes call your authenticated backend a BFF (backend for frontend): your own server routes between your UI and CRISP. This is not another CRISP service you need to deploy.
Identifiers you will use
| Identifier | Source and purpose |
|---|---|
| API key ID + secret | CRISP issues these; they identify your organization’s CRISP integration and enabled features. No partner slug is needed for trading. |
externalUserId | Your stable user identifier within your organization’s CRISP integration. Derive it from your authenticated user, not arbitrary browser input. |
crispAccountId | CRISP's managed account mapping. Persist it with the external ID. |
| Idempotency key | Your durable ID for one action, saved with the exact input before submission. Reuse only for that same intent. |
| Operation / command ID | CRISP's execution record for an order, cancellation or redemption. Use it to follow execution. |
| Order ID | Venue order reference, available when known. Use it for cancellation and order-specific fills. |
| Condition ID / token ID | Market and outcome identifiers from market data. They are not interchangeable. |
Accepted does not mean completed
Save intent → Submit → Command queued/running → Command succeeded
│ │
failed / ambiguous Inspect the result
│
Order open / fills202 means the request was accepted for processing. An operation's succeeded
means that command executed successfully; an accepted limit order may still be
open or only partially filled. Use confirmed fills for executed volume.
| Action | What to follow | When to show completion |
|---|---|---|
| Account creation | waitForAccount / getAccount | Account status is ready, not merely HTTP 202 |
| Place/cancel/redeem | waitForOperation / getOperation | Inspect command outcome, then the affected order/positions/fills |
| Deposit | listTransfers and getFunding | Destination delivery and available balance, not just the source transaction |
| Withdrawal | getWithdrawal, then listTransfers | confirmed is source transfer confirmation; final bridge delivery is separate |
| Referral claim | getReferralSummary | Confirmed payout, not accrual or claim acceptance |
failed and ambiguous are different. An ambiguous command or a lost financial
response may already have executed. Keep the original intent, show “awaiting
confirmation,” and use recovery reads. Do not create a
new key to try again. A polling timeout or abort stops waiting, not execution.
Amounts and unavailable data
- Market buys use a cash budget; market sells and limit orders use shares.
- Prices are decimal cash per share (
"0.62"), not integer cents (62). - Deposit quotes use the source token's base units. Withdrawal amounts use source Polygon pUSD base units (six decimals).
- Use decimal strings for monetary input and exact arithmetic. The redemption
contract is an exception: position
sizeis a number; follow its schema. nullor unavailable buying power is not zero. Preserve last-known display data while refreshing, but never label stale balances or estimates as confirmed.
Next: run the quickstart, or find an exact method in the SDK reference and HTTP API reference.