Skip to main content
POST
Redeem an invite code
The response body shown here is a static example, not live data. After you click Send, your live result appears in a separate panel headed 200 OK. The panel under the status-code tabs is a fixed sample from the spec — its field values (fees, prices, sizes, IDs, timestamps) are placeholders. Use Send, or call the endpoint, for current values.
Redeems a single-use invite code. On success the caller is:
  • bound as a referee of the invite code’s owner (same effect as POST /v1/affiliate/registerAffiliate under the owner’s referral code), and
  • granted perps trading access (a second avenue beside the static API access whitelist; effective within the grant propagation interval, typically under 30 seconds).
The invite code is marked used atomically — if two callers race on the same code, exactly one wins and the other receives 409. The response does not name the code’s owner. The redeemer never learns the address of the trader who invited them; GET /v1/affiliate/myReferrer redacts the same address. Requirements: the code’s owner must currently hold a referral code, self-redemption is rejected, and the standard registration volume gate applies. An already-referred caller may be reassigned — but only when this code is what grants them access. Invite codes are earned by their owner, so the owner takes the referral when redeeming is what actually opens the door; a code that grants nothing may not take another affiliate’s referee: A move is forward-only: the previous affiliate keeps commission already earned and stops accruing from the next fill onward. Since access is granted once, at most one redemption per account can ever move a binding. Redeeming a code owned by the affiliate you are already attributed to is also a 409 — it would spend a code without changing anything. A move is confirmed asynchronously and has no firehose ack, so that path always answers 202 rather than 200. Retry-safe: every step is idempotent. If the response is a 502 (”… retry to complete”), the code is claimed by the caller and retrying the identical request completes the redemption. Guessing guard. Invite codes are short, so this endpoint enforces a tight budget on attempts that name a code which does not exist, on top of the standard rate limit. A caller who submits several unknown codes in quick succession receives 429 with Retry-After; the budget is not consumed by successful redemptions.

Authorizations

X-API-Key
string
header
required

Hex-encoded Ed25519 public key (64 chars). The public key IS the API key — register it via POST /createApiKey. Required on every authenticated request, both read-only and signed.

X-Timestamp
string
header
required

Unix time in nanoseconds as a decimal string (e.g. "1713825891591000000"). Millisecond or second epochs are rejected with 401 Unauthorized. Must be within ±30,000 ms of server wall-clock, or the request is rejected with 401 Unauthorized. Required on all mutating / credential-creating endpoints. This same value must appear as the ct field in the ordersign typed canonical payload (single-order endpoints) or in each element's ct field (batch endpoints).

X-Signature
string
header
required

Lowercase hex-encoded Ed25519 signature (128 chars).

Single-order endpoints (placeOrder, cancelOrder, modifyOrder, and other non-batch mutating routes) sign over the ordersign typed canonical payload — a compact, key-sorted JSON object built from parsed request fields using engine-native integer values:

ct must equal the X-Timestamp header value. Keys in brackets are conditional (omitted when empty). op values: 1=place, 2=cancel, 3=modify. See the ordersign package for field definitions and reference signing code.

Other signed routes (e.g. createApiKey) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.

Batch endpoints (batchPlaceOrders, batchCancelOrders, batchModifyOrders) do NOT use this header. They authenticate with per-element typed ordersign signatures embedded in the request body (see the global auth description and the per-field signature descriptions on OrderRequest / CancelOrderRequest / ModifyOrderRequest).

Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required, except for the signed affiliate reads (see the Referral tag), which require the full header triple; with no body their signing message is X-Timestamp + ACTION. canonicalJSON(body) is the JSON body with object keys sorted lexicographically at every level and no whitespace; the server canonicalizes the received body before verifying, so only the bytes signed over must be canonical. Required on all mutating / credential-creating endpoints.

Body

application/json
address
string
required

Ethereum address of the redeemer (must match signer).

inviteCode
string
required

Invite code to redeem. The canonical form is 6 uppercase base36 characters (A-Z, 0-9); any casing is accepted, and spaces and dashes are stripped so a code copied from a chat message works as sent.

Required string length: 1 - 32

Response

Redemption confirmed by the matching engine (referee binding ack received within the server-side timeout). Trading access follows within the grant propagation interval.

Deliberately does not identify the invite code's owner. Signing the request proves who the caller is, which is no obstacle to redeeming a code purely to learn who owns it, so echoing the owner back made redemption a one-shot referral-code → wallet lookup. Poll GET /v1/affiliate/myReferrer for the binding's code and discount.

status
enum<string>
required
Available options:
submitted