Session Key

Type: SESSION · Weight: 1

Status: Implemented.

POST /api/v3/session-key

Issue (or rotate) the HMAC API key pair bound to the Canton party of an exchange wallet session. This is the path the Rocky web app uses after a wallet connect; institutional integrations receive their keys through onboarding instead and do not call it.

Not on the signed surface: there is no X-MBX-APIKEY / signature. The request is authenticated by the wallet-session bearer token and charged to the per-IP public weight bucket.

Request — JSON body

POST /api/v3/session-key
Authorization: Bearer <exchange wallet session token>
Content-Type: application/json

{ "party": "<canton-party-id>" }

Field	Type	Required	Notes
party	string	yes	Canton party id. Trimmed; 1–512 characters after trimming. Must equal the party bound to the session.

Response — 200 (values illustrative)

{
  "userId": "7c2d1f0e-3a4b-5c6d-8e9f-0a1b2c3d4e5f",
  "key": "9f1c…64 hex…",
  "secret": "4b7e…64 hex…"
}

Field	Type	Notes
userId	string	Deterministic UUIDv5 of the party (rocky-spot:<party>): the same party always maps to the same spot account, so a reconnect sees the same balances and orders.
key	string	64 hex characters; the value to send in X-MBX-APIKEY. The key type is HMAC.
secret	string	64 hex characters; the HMAC-SHA256 shared secret. Returned once.

Every call revokes the previously issued session key for that party (label spot-session:<party>) and returns a fresh pair; a reconnect cannot recover an earlier secret. The new key is on the standard rate tier.

Errors — HTTP status only, no {code,msg} body (except 429)

HTTP	cause
400	party empty or longer than 512 characters, or body not valid JSON.
401	Bearer token missing, invalid, revoked, or expired.
403	The session has no bound Canton party, or party differs from the session's party.
429	-1003 — per-IP public weight exhausted.
500	Database failure.