> ## Documentation Index > Fetch the complete documentation index at: https://docs.joyride.exchange/llms.txt > Use this file to discover all available pages before exploring further. # Request a withdrawal authorization > Reserves the requested Joyride account balance and returns the signed authorization needed to submit a vault withdrawal on Solana. This endpoint does not submit the on-chain transaction. The authenticated account must match `account_id`. The signed `user_wallet` is the embedded wallet registered to that account; the destination may be the connected external wallet's USDC token account. Reuse the same `Idempotency-Key` for every retry of an identical request. A replay returns the same withdrawal id and signed bundle. Reusing a key with different request fields returns `409`. ## OpenAPI ````yaml /_generated/openapi.yaml post /withdrawals openapi: 3.1.0 info: title: Joyride Exchange REST API version: 1.0.0 description: > REST API for the Joyride 0DTE Options Exchange. ## Authentication **Public endpoints** (`/health`, `/v1/market/*`, `/v1/spot/*`, `/v1/oracle/*`) require no authentication. **Competition prize claims** (`/v1/competition/claim`) are self-authenticated by a Solana ed25519 signature over the wallet, Discord handle, and payout destination in the request body. No JWT is required for that endpoint. **Account endpoints** (`/v1/account/*`, `/v1/orders/*`, `/v1/social/profile`, `/v1/social/avatar`) require JWT authentication via one of: 1. `Authorization: Bearer ` header (primary — native clients) 2. `Cookie: joyride_session=` (web clients, set automatically by `/v1/auth/verify`) **Withdrawal endpoints** (`/withdrawals`, `/v1/withdrawals`) require the `Authorization: Bearer ` header. A session cookie alone is not accepted. Obtain a JWT by completing the SIWS (Sign In With Solana) flow: 1. `POST /v1/auth/nonce` with your wallet address to get a nonce 2. Sign the canonical SIWS message with your wallet 3. `POST /v1/auth/verify` with wallet, signature, and message to receive a JWT **Mutating admin endpoints** require a bearer token: ``` Authorization: Bearer ``` ## Data Conventions - **Prices**: Integer values in USDC micros (1 USDC = 1,000,000 micros). Example: `1500000` = $1.50 - **Sizes**: Integer values in millicontracts (1 contract = 1000 millicontracts). Example: `1000` = 1 contract - **Balances**: USDC micros. Example: `10_000_000_000` = $10,000 - **Timestamps**: Unix microseconds (µs since epoch) - **Instrument IDs**: Format `{ASSET}_USDC-{DMMMYY}-{STRIKE}-{C|P}`. Example: `SOL_USDC-28FEB26-150-C` ## Trading **Trading is WebSocket-only.** The HTTP API has no order placement endpoints. See the AsyncAPI spec for WebSocket trading methods. contact: name: Joyride Engineering email: engineering@joyride.exchange license: name: Proprietary servers: - url: https://joyride.exchange/api description: Production security: [] tags: - name: Authentication description: | SIWS (Sign In With Solana) authentication flow. Obtain a JWT for use with all authenticated endpoints. No prior authentication required. - name: Health description: Service health check. - name: Market Data description: Publicly accessible market data. No authentication required. - name: Account description: User-specific account data. Requires user identification. - name: Orders description: User order history. Requires user identification. - name: Withdrawals description: Request signed withdrawal authorizations and list withdrawal history. - name: Social description: Social features — profiles, leaderboard, and activity. - name: Referrals description: Referral-code validation and attribution surfaces. - name: Competition description: Competition-specific collection flows. - name: Spot description: Spot prices and volatility data. - name: Oracle description: Oracle data — prices, TWAP previews, and settlement timing. - name: AI Chat description: > AI-powered trading assistant. Uses SIWS (Sign In With Solana) authentication and JWT sessions. Returns responses as Server-Sent Events (SSE). - name: Admin description: Administrative operations. Requires admin bearer token. paths: /withdrawals: post: tags: - Withdrawals summary: Request a withdrawal authorization description: > Reserves the requested Joyride account balance and returns the signed authorization needed to submit a vault withdrawal on Solana. This endpoint does not submit the on-chain transaction. The authenticated account must match `account_id`. The signed `user_wallet` is the embedded wallet registered to that account; the destination may be the connected external wallet's USDC token account. Reuse the same `Idempotency-Key` for every retry of an identical request. A replay returns the same withdrawal id and signed bundle. Reusing a key with different request fields returns `409`. operationId: requestWithdrawalAuthorization parameters: - name: Idempotency-Key in: header required: true description: >- Client-generated key that remains stable across retries of this request. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WithdrawalAuthorizationRequest' responses: '200': description: Signed withdrawal authorization bundle content: application/json: schema: $ref: '#/components/schemas/WithdrawalAuthorizationBundle' '400': description: Invalid request, unknown account, or insufficient balance content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid bearer token, or account mismatch content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Idempotency key was already used with different request fields content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' '503': description: Reservation is pending or a dependency is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' security: - aiAuth: [] components: schemas: WithdrawalAuthorizationRequest: type: object properties: account_id: type: integer format: int32 minimum: 0 description: Joyride account id. Must match the authenticated JWT account claim. example: 1000000 destination_token_account: type: string description: >- Base58 Solana USDC token-account address that will receive the withdrawal. example: EVMJiDJicBLnsZABt2Zsi8afzwa4okWNaJibjxxEPJuC amount: type: string description: >- USDC decimal amount exactly representable at six-decimal precision. Insignificant trailing zeros beyond six places are accepted. example: '25.12345600' required: - account_id - destination_token_account - amount WithdrawalAuthorizationBundle: type: object properties: withdrawal_id: type: string description: Unsigned 64-bit withdrawal id, represented as a decimal string. example: '812' account_id: type: integer format: int32 example: 1000000 raw_amount: type: string description: USDC base units at six-decimal precision. example: '25123456' amount: type: string description: Core fixed-eight-decimal USDC amount. example: '25.12345600' user_wallet: type: string description: >- Embedded Solana wallet authorized to withdraw from this Joyride account. example: 4etJNAJtLFrJERJwejzmCA6PZGiVwP11j2mfUkGYWqwS destination_token_account: type: string description: Base58 Solana token-account address bound into the authorization. example: EVMJiDJicBLnsZABt2Zsi8afzwa4okWNaJibjxxEPJuC mint: type: string description: Base58 USDC mint address bound into the authorization. example: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU issued_at_unix_timestamp: type: integer format: int64 description: Signed authorization issue time in Unix seconds. example: 1752000000 expiry_unix_timestamp: type: integer format: int64 description: Signed authorization expiry time in Unix seconds. example: 1752000060 authorization_message_b64: type: string format: byte description: Canonical 256-byte WithdrawalAuthorizationV3 message. authorization_signature_b64: type: string format: byte description: Ed25519 signature over `authorization_message_b64`. withdraw_authority: type: string description: Base58 Ed25519 public key that signed the authorization. kms_key_id: type: string description: Deployment key identifier used to sign the authorization. required: - withdrawal_id - account_id - raw_amount - amount - user_wallet - destination_token_account - mint - issued_at_unix_timestamp - expiry_unix_timestamp - authorization_message_b64 - authorization_signature_b64 - withdraw_authority - kms_key_id Error: type: object properties: error: type: string description: >- Human-readable error message (auth failures may include an `auth_*` code prefix) example: Instrument not found required: - error responses: InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: aiAuth: type: http scheme: bearer description: | JWT obtained from POST /v1/auth/verify after SIWS authentication. Include as: `Authorization: Bearer ` ````