> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xo.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Derive API key

> Deterministically derive the caller's existing key — returns
the oldest key in insertion order so repeat callers see a
stable result. Never mints; use `POST /auth/api-key` for that.




## OpenAPI

````yaml /api-reference/openapi.yaml get /auth/derive-api-key
openapi: 3.0.3
info:
  title: XO Orderbook API
  description: |
    Public REST surface of the XO CLOB API.

    XO mainnet chain id is `3223`. The EIP-712 order domain is
    `XO Market CLOB` with `verifyingContract` set to the
    [CTF Exchange](/) address. See
    [Smart accounts](../guides/smart-accounts) for the smart-account
    identity model and ERC-1271 order signing.

    Wire conventions:
      * Prices are trimmed decimal strings (e.g. `"0.5"`, `"0.555"`).
      * Sizes are decimal-string integers in human shares.
      * Timestamps in trade and book responses are stringified Unix
        seconds / milliseconds (the SDK uses `TimestampSeconds<String>`
        / `TimestampMilliSeconds<String>`).
      * Token IDs are decimal U256 strings; condition IDs are
        `0x`-prefixed 32-byte hex.
  version: 1.0.0
  contact:
    name: XO Market
    url: https://beta.xo.market
servers:
  - url: https://orderbooks.xo.market
    description: Mainnet (XO chain id 3223)
security: []
tags:
  - name: Authentication
    description: >-
      Create and manage API keys. The L1 ClobAuth EIP-712 flow mints HMAC
      credentials that authenticate every other private request.
  - name: Market Data
    description: >-
      Public reads for books, prices, midpoints, spreads, last trades, and price
      history. Also includes server time and per-token configuration.
  - name: Markets
    description: >-
      Discovery for tradable markets, including pagination and SDK-compatible
      simplified shapes.
  - name: Trade
    description: Place, cancel, and inspect orders and trades for the authenticated maker.
  - name: Account
    description: Maker balance, allowance, positions, and claimable settled positions.
paths:
  /auth/derive-api-key:
    get:
      tags:
        - Authentication
      summary: Derive API key
      description: |
        Deterministically derive the caller's existing key — returns
        the oldest key in insertion order so repeat callers see a
        stable result. Never mints; use `POST /auth/api-key` for that.
      responses:
        '200':
          description: OK. Returns the caller's existing (oldest) key, NOT a fresh one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyTriplet'
              example:
                apiKey: 7a3f9c1d-8b2e-4a5c-9d1e-2f3a4b5c6d7e
                secret: dGhpcy1pcy1hbi1leGFtcGxlLWhtYWMtc2VjcmV0LWtleS1iYXNlNjQ=
                passphrase: 9f3a2b1c4d5e6f708192a3b4c5d6e7f8
        '404':
          description: |
            Caller has no API key yet. SDKs use this 404 to fall through
            to `POST /auth/api-key` (recover-or-create flow).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  no API key found for address
                  0xCAFE000000000000000000000000000000000A11
      security:
        - L1ClobAuth: []
      x-codeSamples:
        - lang: Rust
          label: xo-orderbook-client-rs
          source: >
            use alloy::signers::local::LocalSigner;

            use xo_orderbook_client::orderbook::{Client, Config};


            let signer =
            LocalSigner::from_bytes(&std::env::var("XO_PRIVATE_KEY")?.parse()?)?;

            let client = Client::new("https://orderbooks.xo.market",
            Config::default())?;

            let creds = client.derive_api_key(&signer).await?;

            // Returns the existing (oldest) key. 404 if no key exists yet.
components:
  schemas:
    ApiKeyTriplet:
      type: object
      description: |
        camelCase wire keys per CLOB SDK contract. **The triplet is the
        full credential** — the secret/passphrase are never returned
        again. Store them on receipt.
      required:
        - apiKey
        - secret
        - passphrase
      properties:
        apiKey:
          type: string
          format: uuid
          description: UUIDv4 — sent as `POLY_API_KEY` header on every L2 HMAC request.
        secret:
          type: string
          description: |
            Base64-encoded HMAC secret. Used to sign the request canonical
            string; never sent on the wire after creation.
        passphrase:
          type: string
          description: |
            Sent as `POLY_PASSPHRASE` header. Distinct from the secret —
            both must match for the request to authenticate.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
  securitySchemes:
    L1ClobAuth:
      type: apiKey
      in: header
      name: XO_ADDRESS
      description: >-
        L1 ClobAuth EIP-712 wallet signature. See
        [Authentication](/api-reference/authentication).

````