> ## 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. # Provision a core account with a referral code > Self-service signup for a new wallet. The caller first obtains a server-issued nonce from `/v1/onboarding/nonce`, signs the purpose-bound signup message (with the nonce embedded) with the wallet, and submits the referral code bound into that message. The platform BFF consumes the nonce (single use), allocates a durable account id, consumes the referral code, and submits core `account_create` with a scoped provisioner token. Fresh accounts start unfunded. Devnet/Mainnet balances come from the vault/deposit path; there is no server-side paper funding. ## OpenAPI ````yaml /_generated/openapi.yaml post /v1/onboarding/signup 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: /v1/onboarding/signup: post: tags: - Referrals summary: Provision a core account with a referral code description: | Self-service signup for a new wallet. The caller first obtains a server-issued nonce from `/v1/onboarding/nonce`, signs the purpose-bound signup message (with the nonce embedded) with the wallet, and submits the referral code bound into that message. The platform BFF consumes the nonce (single use), allocates a durable account id, consumes the referral code, and submits core `account_create` with a scoped provisioner token. Fresh accounts start unfunded. Devnet/Mainnet balances come from the vault/deposit path; there is no server-side paper funding. operationId: signupWithReferralCode requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OnboardingSignupRequest' responses: '200': description: Account exists or was created for the wallet content: application/json: schema: $ref: '#/components/schemas/OnboardingSignupResponse' '401': description: | Wallet signature proof is missing, malformed, or invalid (`INVALID_SIGNUP_PROOF`), or the nonce in the signed message was not issued by the server, was already consumed, or has expired (`NONCE_INVALID`). On `NONCE_INVALID`, fetch a fresh nonce from `/v1/onboarding/nonce` and re-sign. content: application/json: schema: $ref: '#/components/schemas/ReferralErrorResponse' examples: invalidProof: summary: Signature proof failed verification value: error: INVALID_SIGNUP_PROOF nonceInvalid: summary: Nonce unissued, consumed, or expired value: error: NONCE_INVALID '409': description: Code is missing, inactive, exhausted, or malformed content: application/json: schema: $ref: '#/components/schemas/ReferralErrorResponse' example: error: CODE_UNAVAILABLE '429': description: Per-IP signup rate limit exceeded headers: retry-after: description: Seconds until the request may be retried. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ReferralErrorResponse' example: error: RATE_LIMITED '503': description: >- Core provisioning, query lookup, or platform DB temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ReferralErrorResponse' security: [] components: schemas: OnboardingSignupRequest: type: object properties: code: type: string description: Referral code to consume for signup. example: ALICE wallet: type: string description: Base58 Solana wallet address being provisioned. example: GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8 message: type: string description: >- Purpose-bound signup message signed by the wallet. The referral code line must use the normalized `code` value, meaning trimmed and uppercased. The nonce line must carry a server-issued nonce from `POST /v1/onboarding/nonce`; each nonce is single-use. example: |- Sign up for Joyride Wallet: GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8 Referral code: ALICE Nonce: 4Wz9pJb1rQx7cVd2mKf8sT3u signature: type: string description: Base58 Ed25519 signature over `message`. example: 3Qf2Bz... required: - code - wallet - message - signature OnboardingSignupResponse: type: object properties: provisioned: type: boolean description: True when the wallet has a core account after this request. example: true account_id: type: integer description: Core account id assigned to this wallet. example: 1000000 created: type: boolean description: True when this request submitted a fresh core account_create. example: true required: - provisioned - account_id - created ReferralErrorResponse: type: object properties: error: type: string description: Human-readable message or machine-readable referral error code. example: CODE_UNAVAILABLE code: type: string description: >- Optional machine-readable code. Present on auth/upstream failures; 409 and 429 use `error`. example: AUTH_UPSTREAM_ERROR required: - error ````