API Connectivity

Endpoints

Everything is served from the public origin https://joyride.exchange, with no separate API host.

Surface	URL	Auth
Trading WebSocket (RFQ)	`wss://joyride.exchange/api/client`	SIWS on the socket (`public/auth` or `public/session_resume`)
Oracle WebSocket (spot price)	`wss://joyride.exchange/api/oracle`	None
Query HTTP (self-scoped reads: RFQ fills, RFQ positions, vault subaccount)	`https://joyride.exchange/api/query/*`	`Authorization: Bearer <session_token>`
Public market HTTP (config, instruments, mark IV)	`https://joyride.exchange/api/v1/market/*`	None

The trading WebSocket speaks JSON-RPC 2.0. Every request carries "jsonrpc": "2.0", an id, a method, and optional params. Once a request parses, its response echoes the id; malformed JSON that cannot be parsed returns a parse error with "id": null. Server pushes arrive as "method": "subscription" notifications with no id.

Authentication

Identity is an ed25519 keypair. There are no API keys. An account belongs to a Solana wallet public key, created in the app at joyride.exchange, and that keypair signs in over the API, from the CLI, or in the app. Sign-in uses three methods on the trading WebSocket.

Method	Request	Response	Errors
`public/get_nonce`	none; `params` is ignored	`{ "nonce": "<base58>" }`, single use, valid for 300 seconds	none
`public/auth`	`{ "wallet", "signature": "<base58 signature>", "message" }`	`{ "wallet", "account_id", "roles", "session_token" }`	`1001` bad signature, message mismatch, nonce expired or reused, unknown account
`public/session_resume`	`{ "session_token": "<jwt>" }`	`{ "wallet", "account_id", "roles" }`; the socket is now authenticated and no new token is issued	`1001` token expired or invalid, unknown or reassigned account

Request a nonce

{"jsonrpc":"2.0","id":1,"method":"public/get_nonce"}

{"jsonrpc":"2.0","id":1,"result":{"nonce":"3fA9kLm2PqRs7TuVwXyZ1bCdEfGh4JkL"}}

Sign and authenticate

The message is built byte for byte as below: a blank line between the greeting and the Wallet: line, a single newline before Nonce:.

Sign in to Joyride

Wallet: {wallet}
Nonce: {nonce}

The signature is ed25519 over the UTF-8 bytes of that message, base58-encoded (64 bytes). The request carries the wallet, the signature, and the exact message signed. The server rebuilds the message from wallet and the nonce inside message and rejects any deviation, including a trailing newline or reordered lines.

{"jsonrpc":"2.0","id":2,"method":"public/auth","params":{"wallet":"7Gx2XvMk9Z1sZbY3qJ8pKcWnD4tFhRr6sA2eLmN5uVwQ","signature":"<base58 signature>","message":"Sign in to Joyride\n\nWallet: 7Gx2XvMk9Z1sZbY3qJ8pKcWnD4tFhRr6sA2eLmN5uVwQ\nNonce: 3fA9kLm2PqRs7TuVwXyZ1bCdEfGh4JkL"}}

{"jsonrpc":"2.0","id":2,"result":{"wallet":"7Gx2XvMk9Z1sZbY3qJ8pKcWnD4tFhRr6sA2eLmN5uVwQ","account_id":1042,"roles":["rfq_quoter"],"session_token":"<jwt>"}}

roles lists what the account may do. An account the exchange has designated as a market maker carries rfq_quoter; every other account’s array is empty. A wallet with no account is rejected with 1001. Signing in never creates an account.

Resume on reconnect

A stored session_token authenticates a new socket without a fresh signature. Resume checks that the wallet still owns the account_id in the token and returns roles from live account state. That response is a snapshot: every RFQ action checks the live role, and delivery of new open requests rechecks it for each subscribed socket. A revocation therefore blocks maker calls and stops new open requests immediately on an existing socket; a grant immediately lets that socket subscribe and call maker methods. A revoked quoter remains subscribed to targeted lifecycle and fill events for quotes where it is already the counterparty.

{"jsonrpc":"2.0","id":3,"method":"public/session_resume","params":{"session_token":"<jwt>"}}

{"jsonrpc":"2.0","id":3,"result":{"wallet":"7Gx2XvMk9Z1sZbY3qJ8pKcWnD4tFhRr6sA2eLmN5uVwQ","account_id":1042,"roles":["rfq_quoter"]}}

A 1001 on resume means the cached token is no longer valid; the full nonce, sign, auth sequence is required. public/session_resume on a socket already authenticated as the same account refreshes that session and evicts nothing.

Session token

Parameter	Value	Applies to
Format	JWT, HS256, issued by the trading gateway	`session_token`
Lifetime	24 hours from issue (`exp` claim)	`session_token` TTL
Revocation	None; a token stays valid until `exp`	`session_token`

The session token is the JWT that public/auth returns after the wallet signs the nonce. It authenticates the trading WebSocket and the query API; a quote or an acceptance additionally carries a wallet signature, which the token cannot produce.

Sessions per account

Parameter	Value	Applies to
Concurrent authenticated sessions	3 per account	Trading WebSocket
Eviction on a 4th session	Oldest session closed with WebSocket close code `4001`, reason `session_limit`	Trading WebSocket
Delivery of RFQ pushes	Only authenticated sockets that called `rfq.subscribe` (the account’s own requests) or `rfq.maker.subscribe` (requests open for quoting)	Trading WebSocket

RFQ subscriptions are per socket; subscribing one session does not subscribe the account’s other sessions. A client normally needs one authenticated socket and must subscribe on it after connecting or reconnecting. A client closed with 4001 and reason session_limit must not reconnect automatically: the reconnect evicts the newer session and the two clients evict each other in a loop. Reconnect only on an operator action.

Keepalive

Parameter	Value	Applies to
Server-initiated ping	Never	Trading WebSocket
Unauthenticated idle reap	60 seconds without an inbound text or binary message	Trading WebSocket

The server never pings. The client sends a protocol-level WebSocket ping at least every 30 seconds to keep intermediaries from dropping a quiet flow, and the gateway answers each with a pong. Protocol ping and pong frames do not refresh the unauthenticated idle deadline. Until authentication succeeds, send a text or binary JSON-RPC message within each 60-second interval or the gateway reaps the socket with error 1001; authenticate promptly rather than using public calls only as a keepalive.

Rate budget

Parameter	Value	Applies to
Request budget	100 charged requests per one-second fixed window per account	Private order and margin calls plus RFQ methods other than the two subscribe methods, counted together across sessions
Exempt methods	No budget charge	`public/*`, `rfq.subscribe`, `rfq.maker.subscribe`
Over budget	Error `1200` with `data.error` `RFQ_RATE_LIMITED` for charged `rfq.` methods; error `1007` only for the order-book `private/` methods, which an RFQ client does not call; both `retryable: true`	The rejected request only; the socket stays open

The budget is per account, so three sessions share it. A request consumes one unit when it reaches the limiter, even if later processing fails. For a maker, rfq.maker.poll, rfq.maker.respond, and rfq.maker.decline are charged; rfq.maker.subscribe is not.

{"jsonrpc":"2.0","id":4,"error":{"code":1200,"message":"RFQ rate limit exceeded","data":{"error":"RFQ_RATE_LIMITED","message":"RFQ rate limit exceeded","operation_id":"rfq-17","retryable":true}}}

The fixed one-second window begins with the account’s first charged request; it is not aligned to a wall-clock second. After the window has elapsed, the rejected request can be resent as is.

Error codes

Errors use the JSON-RPC envelope { "code", "message", "data"? }. Close codes are WebSocket close frames, not JSON-RPC errors.

Code	Surface	Meaning	Client action
`1001`	Trading WebSocket	Authentication or session failure: bad signature, expired nonce, expired or invalid token, unknown or reassigned account, or the 60-second idle reap	Discard any cached token, run `public/get_nonce` then `public/auth`, and resend
`1007`	Trading WebSocket, order-book `private/*` methods only	Rate limit exceeded on a non-RFQ method; an RFQ client receives `1200` / `RFQ_RATE_LIMITED` instead	Retry after backoff; nothing was admitted
`1200`	Trading WebSocket	RFQ error; `data.error` carries the RFQ code (for example `RFQ_WRONG_ROLE` when the socket is not authenticated, `RFQ_NOT_READY`, or `RFQ_RATE_LIMITED` when an `rfq.*` call exceeds the account budget), plus `operation_id`, `retryable`, and `rfq_id` or `quote_id` where known	Branch on `data.error`; retry the same call only when `data.retryable` is `true`
`4001` (close)	Trading WebSocket, reason `session_limit`	A fourth session evicted this one	Do not auto-reconnect; alert and wait for an operator

An rfq.* call made before public/auth or public/session_resume returns 1200 with data.error: "RFQ_WRONG_ROLE" and data.retryable: false, not 1001. Do not repeat the unchanged call on the unauthenticated socket. First authenticate or resume the session, then issue the RFQ call again as a new attempt. The 1200 frame:

{"jsonrpc":"2.0","id":6,"error":{"code":1200,"message":"RFQ chain-service state is not warm","data":{"error":"RFQ_NOT_READY","message":"RFQ chain-service state is not warm","operation_id":"rfq-18","retryable":true,"rfq_id":"0192f1a3b4c5d6e7f8091a2b3c4d5e6f"}}}

The standard JSON-RPC codes (-32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal) follow the JSON-RPC 2.0 specification. A parse failure returns "id": null; once parsing succeeds, errors use the request’s id. -32602 is returned only for malformed public/* params. On an rfq.* method, malformed or unknown params are 1200 with data.error RFQ_INVALID_PARAMS, and an instrument symbol that is not listed or not open is 1200 with data.error RFQ_INVALID_INSTRUMENT.

Support

Support for live makers is support@joyride.exchange. A report that includes the operation_id from a 1200 error, the rfq_id or quote_id in question, and the UTC time of the event can be traced directly. operation_id is a per-process counter (rfq-<n>) that restarts when the gateway restarts, so the UTC time is what makes it unique. Next: Becoming an RFQ Quoter

Market Makers

Reference

Endpoints

Authentication

Request a nonce

Sign and authenticate

Resume on reconnect

Session token

Sessions per account

Keepalive

Rate budget

Error codes

Support

​Endpoints

​Authentication

​Request a nonce

​Sign and authenticate

​Resume on reconnect

​Session token

​Sessions per account

​Keepalive

​Rate budget

​Error codes

​Support

Endpoints

Authentication

Request a nonce

Sign and authenticate

Resume on reconnect

Session token

Sessions per account

Keepalive

Rate budget

Error codes

Support