Fees, referrals and combined claims

Read the active program

GET /v1/fee-program returns the effective program. Render its referral rules, levels and rates dynamically; up to five levels are supported. Do not hardcode PW Market's current rates into another integration. Fee changes create a new version and do not rewrite policy already pinned to accepted orders.

Rates are basis points of eligible matched trading notional. 100 bps is 1% of that notional—not 1% of another fee. Buy/sell charge sides come from the program. The currently enforced total partner-program cap is 1,000 bps. CRISP approves commercial configuration and collection setup; dashboard owner/operators can manage permitted program settings. The HMAC API exposes the active program for reading, not a public arbitrary fee-program write route.

Attribute the direct referrer

After both accounts exist and before first trade:

PUT /v1/accounts/{referredExternalUserId}/referrer
Idempotency-Key: referral-edge-unique-001

{ "referrerExternalUserId": "example:referrer-123" }

Requires accounts:write. Supply only the direct referrer. CRISP validates tenant scope and graph safety and resolves the configured ancestors. Attribution is immutable; do not offer user-driven reparenting after joining. Capture referral links in your own product; authenticate eligibility before calling CRISP. The order records its ancestry and program at acceptance. Missing eligible ancestors follow the program's treasury fallback.

Earnings and history

GET /v1/accounts/{externalUserId}/referral-earnings?from=2026-09-01&to=2026-09-30&granularity=daily&limit=31

Requires fees:read. Response data includes cadence, from, to, granularity, earnings, series, levels, and claimEarnings. Dates are UTC; granularity is daily/weekly/monthly; limit 1–366 (default 31), bounded date window. Use levels for per-level earned amounts, not a hardcoded two-level UI. Historical reporting windows do not expire older unpaid allocations.

• Accrued: earned allocations from eligible fills.
• Collected: collection from the trader into the fee collector; NOT referrer payout.
• Claimable: settled, reconciled and closed-day rewards eligible to claim.
• Paid out: a confirmed beneficiary payout, not mere request acceptance.

User-facing summaries can focus on accrued, claimable and paid out. Keep the internal collection distinction when reconciling. Current-day accrual is not immediately claimable; daily close may wait for collection/reconciliation.

One claim for all eligible days

POST /v1/accounts/{externalUserId}/referral-claims
Idempotency-Key: referral-claim-unique-001

{ "all": true }

Requires fees:write and enabled settlement. Your backend authorizes the logged-in beneficiary; do not let arbitrary users claim for another external ID. CRISP derives payout recipient from their managed wallet. The request accepts no user-supplied payout address or amount.

202 returns claims, aggregate amountUsdc and dayCount. All eligible days are linked to one payout backing record and paid as one combined transfer. Daily entries retain their amounts and may share one claim ID/transaction; totalAmountUsdc is the batch total. Do not display or sum it once per day. Show pending until the claim is confirmed; refresh earnings for payout state.

Concurrent/duplicate requests cannot assign the same allocation twice. Still disable duplicate UI submission and retain the original intent key. HTTP 409 with referral_fee_nothing_claimable means no eligible unclaimed rewards remain. Backing conflicts or historical rewards spanning collection wallets require CRISP reconciliation; never tell users to bypass this by changing beneficiary/destination.

Compatibility { "feeDay": "YYYY-MM-DD" } claims remain available, but new UIs should use { "all": true }, not a loop of daily claims. Do not send both fields.

Partner treasury is separate

/v1/fee-schedule and /v1/fee-claims remain the fee-schedule/treasury compatibility surface. Treasury POST uses feeDay and recipientAddress; it is NOT the end-user referral claim endpoint. Coordinate configured treasury payout policy with CRISP. Program-wide collected totals include allocations that are not partner income; show the net treasury share separately in operator reporting.