openapi: 3.1.0
info:
  title: Xochi API
  version: 1.3.0
  summary: The Agentic Dark Pool on Ethereum. Private execution via stealth settlement; ERC-8262 (Xochi's ZK Compliance Oracle) is the compliance design and is not yet live.
  description: |-
    HTTP API for the Xochi protocol. Submit intents, quote/execute swaps,
    claim stealth settlements, query trust tier and attestation state.
    Privacy is free by default; attestation-based trust scoring unlocks
    lower fees and deeper privacy.

    Auth is wallet-first: trade by signing the EIP-712 intent (no Xochi ID
    required). Member (passkey JWT or service token), Mandate, and Guest (x402
    pay-per-call) layer on top when their headers are present.

    This spec is GENERATED from packages/shared/src/contract.ts (the same zod
    schemas the worker validates against). Do not edit by hand -- run
    `node scripts/generate-openapi.mjs`.

    Companion files:
      - /llms.txt and /llms-full.txt for human + LLM readable protocol summary
      - /.well-known/agents.json for agent discovery + x402 catalog
  contact:
    name: Xochi
    url: https://xochi.fi
  license:
    name: MIT
    url: https://github.com/xochi-fi/xochi/blob/main/LICENSE
servers:
  - url: https://api.xochi.fi
    description: Production
tags:
  - name: intents
    description: Market and limit order lifecycle
  - name: stealth
    description: ERC-5564/6538 stealth address registration, scanning, claiming
  - name: settlements
    description: Claimable settlements and oracle proof verification
  - name: tiers
    description: Trust score, attestations, ZK tier proofs
  - name: solver
    description: Solver revenue and stats (Riddler is the protocol solver)
  - name: prices
    description: Public price feed (DeFi Llama-backed, edge-cached)
  - name: capabilities
    description: Live solver capability matrix (chains, tokens, order bounds)
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Passkey-issued JWT (browser) or wallet-signature JWT (agent). See `/api/auth/login/options` for the browser flow; agents use the wallet-signature path documented in `/.well-known/agents.json`.
  schemas: {}
  parameters: {}
paths:
  /api/intent/quote:
    post:
      operationId: quoteIntent
      summary: Quote a market swap
      description: "Returns a signed quote for a cross-chain swap, valid ~30s. Public: a quote carries no user data. `can_solve:false` (200) is an honest unsolvable quote; a 503 is a retryable solver-unavailable signal."
      tags:
        - intents
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                wallet:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                from_chain_id:
                  type: integer
                to_chain_id:
                  type: integer
                from_token:
                  anyOf:
                    - type: string
                      pattern: ^0x[a-fA-F0-9]{40}$
                    - type: string
                      pattern: ^T[1-9A-HJ-NP-Za-km-z]{33}$
                to_token:
                  anyOf:
                    - type: string
                      pattern: ^0x[a-fA-F0-9]{40}$
                    - type: string
                      pattern: ^T[1-9A-HJ-NP-Za-km-z]{33}$
                from_amount:
                  type: string
                deadline:
                  type: integer
                  exclusiveMinimum: 0
                slippage_bps:
                  type: integer
                  minimum: 1
                  maximum: 5000
                trust_score:
                  type: integer
                  minimum: 0
                settlement_preference:
                  type: string
                  enum: &a1
                    - public
                    - shielded
                    - stealth
                gasless:
                  type: boolean
                recipient_address:
                  anyOf:
                    - type: string
                      pattern: ^0x[a-fA-F0-9]{40}$
                    - type: string
                      pattern: ^T[1-9A-HJ-NP-Za-km-z]{33}$
                stealth_meta_address:
                  type: object
                  properties:
                    spending_pub_key:
                      type: string
                    viewing_pub_key:
                      type: string
                    chain_id:
                      type: integer
                  required:
                    - spending_pub_key
                    - viewing_pub_key
                    - chain_id
              required:
                - wallet
                - from_chain_id
                - to_chain_id
                - from_token
                - to_token
                - from_amount
                - deadline
                - slippage_bps
                - settlement_preference
      responses:
        "200":
          description: Quote returned (solvable or unsolvable)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  intent_id:
                    type: string
                  quote_id:
                    type: string
                  can_solve:
                    type: boolean
                  to_amount:
                    type: string
                  min_to_amount:
                    type: string
                  xochi_fee:
                    type: string
                  xochi_fee_rate:
                    type: string
                  fee_breakdown:
                    type: object
                    properties:
                      tier:
                        type: string
                        enum: &a2
                          - standard
                          - trusted
                          - verified
                          - premium
                          - institutional
                      asset_class:
                        type: string
                        enum: &a3
                          - stable
                          - volatile
                      gas_floor:
                        type: object
                        properties:
                          amount:
                            type: string
                          usd:
                            type: string
                        required:
                          - amount
                          - usd
                      solver_fee_bps:
                        type: number
                      solver_fee:
                        type: string
                      price_impact_bps:
                        type: number
                      price_impact:
                        type: string
                      venue_fee_bps:
                        type: number
                      venue_fee:
                        type: string
                      routing_fee_bps:
                        type: number
                      routing_fee:
                        type: string
                      total_bps:
                        type: number
                      total_fee:
                        type: string
                      total_usd:
                        type: string
                      surplus_share_pct:
                        type: number
                    required:
                      - tier
                      - asset_class
                      - gas_floor
                      - solver_fee_bps
                      - solver_fee
                      - price_impact_bps
                      - price_impact
                      - venue_fee_bps
                      - venue_fee
                      - routing_fee_bps
                      - routing_fee
                      - total_bps
                      - total_fee
                      - total_usd
                      - surplus_share_pct
                  estimated_gas_cost:
                    type: string
                  expiry:
                    type: string
                  gasless:
                    type: boolean
                  gasless_fee:
                    type: string
                  payment_method:
                    type: string
                    enum: &a4
                      - erc3009
                      - permit2
                      - pimlico
                      - x402
                      - mpp
                      - approval
                  route:
                    type: object
                    additionalProperties: {}
                  eip712:
                    type: object
                    properties:
                      domain:
                        type: object
                        properties:
                          name:
                            type: string
                          version:
                            type: string
                          chainId:
                            type: integer
                          verifyingContract:
                            type: string
                            pattern: ^0x[a-fA-F0-9]{40}$
                          salt:
                            type: string
                        required:
                          - name
                          - version
                          - chainId
                      types:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              type:
                                type: string
                            required:
                              - name
                              - type
                      primaryType:
                        type: string
                      message:
                        type: object
                        additionalProperties: {}
                    required:
                      - domain
                      - types
                      - primaryType
                      - message
                  pull_authorization:
                    type: object
                    properties:
                      domain:
                        type: object
                        properties:
                          name:
                            type: string
                          version:
                            type: string
                          chainId:
                            type: integer
                          verifyingContract:
                            type: string
                            pattern: ^0x[a-fA-F0-9]{40}$
                          salt:
                            type: string
                        required:
                          - name
                          - version
                          - chainId
                      types:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              type:
                                type: string
                            required:
                              - name
                              - type
                      primaryType:
                        type: string
                      message:
                        type: object
                        additionalProperties: {}
                    required:
                      - domain
                      - types
                      - primaryType
                      - message
                  deposit_address:
                    type: string
                  deposit_attestation:
                    type: string
                  deposit_deadline:
                    type: integer
                  recipient_address:
                    anyOf:
                      - type: string
                        pattern: ^0x[a-fA-F0-9]{40}$
                      - type: string
                        pattern: ^T[1-9A-HJ-NP-Za-km-z]{33}$
                  settlement_options:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum: *a1
                        available:
                          type: boolean
                        reason:
                          type: string
                      required:
                        - type
                        - available
                  claim_info:
                    type: object
                    properties:
                      factory_address:
                        type: string
                        pattern: ^0x[a-fA-F0-9]{40}$
                      salt:
                        type: integer
                    required:
                      - factory_address
                      - salt
                  nonce:
                    type: integer
                    minimum: 0
                  error:
                    type: string
                  error_category:
                    type: string
                  detail:
                    type: string
                required:
                  - success
                  - intent_id
                  - quote_id
                  - can_solve
                  - expiry
                additionalProperties: false
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "503":
          description: Solver temporarily unavailable (retryable)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  intent_id:
                    type: string
                  quote_id:
                    type: string
                  can_solve:
                    type: boolean
                  to_amount:
                    type: string
                  min_to_amount:
                    type: string
                  xochi_fee:
                    type: string
                  xochi_fee_rate:
                    type: string
                  fee_breakdown:
                    type: object
                    properties:
                      tier:
                        type: string
                        enum: *a2
                      asset_class:
                        type: string
                        enum: *a3
                      gas_floor:
                        type: object
                        properties:
                          amount:
                            type: string
                          usd:
                            type: string
                        required:
                          - amount
                          - usd
                      solver_fee_bps:
                        type: number
                      solver_fee:
                        type: string
                      price_impact_bps:
                        type: number
                      price_impact:
                        type: string
                      venue_fee_bps:
                        type: number
                      venue_fee:
                        type: string
                      routing_fee_bps:
                        type: number
                      routing_fee:
                        type: string
                      total_bps:
                        type: number
                      total_fee:
                        type: string
                      total_usd:
                        type: string
                      surplus_share_pct:
                        type: number
                    required:
                      - tier
                      - asset_class
                      - gas_floor
                      - solver_fee_bps
                      - solver_fee
                      - price_impact_bps
                      - price_impact
                      - venue_fee_bps
                      - venue_fee
                      - routing_fee_bps
                      - routing_fee
                      - total_bps
                      - total_fee
                      - total_usd
                      - surplus_share_pct
                  estimated_gas_cost:
                    type: string
                  expiry:
                    type: string
                  gasless:
                    type: boolean
                  gasless_fee:
                    type: string
                  payment_method:
                    type: string
                    enum: *a4
                  route:
                    type: object
                    additionalProperties: {}
                  eip712:
                    type: object
                    properties:
                      domain:
                        type: object
                        properties:
                          name:
                            type: string
                          version:
                            type: string
                          chainId:
                            type: integer
                          verifyingContract:
                            type: string
                            pattern: ^0x[a-fA-F0-9]{40}$
                          salt:
                            type: string
                        required:
                          - name
                          - version
                          - chainId
                      types:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              type:
                                type: string
                            required:
                              - name
                              - type
                      primaryType:
                        type: string
                      message:
                        type: object
                        additionalProperties: {}
                    required:
                      - domain
                      - types
                      - primaryType
                      - message
                  pull_authorization:
                    type: object
                    properties:
                      domain:
                        type: object
                        properties:
                          name:
                            type: string
                          version:
                            type: string
                          chainId:
                            type: integer
                          verifyingContract:
                            type: string
                            pattern: ^0x[a-fA-F0-9]{40}$
                          salt:
                            type: string
                        required:
                          - name
                          - version
                          - chainId
                      types:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              type:
                                type: string
                            required:
                              - name
                              - type
                      primaryType:
                        type: string
                      message:
                        type: object
                        additionalProperties: {}
                    required:
                      - domain
                      - types
                      - primaryType
                      - message
                  deposit_address:
                    type: string
                  deposit_attestation:
                    type: string
                  deposit_deadline:
                    type: integer
                  recipient_address:
                    anyOf:
                      - type: string
                        pattern: ^0x[a-fA-F0-9]{40}$
                      - type: string
                        pattern: ^T[1-9A-HJ-NP-Za-km-z]{33}$
                  settlement_options:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum: *a1
                        available:
                          type: boolean
                        reason:
                          type: string
                      required:
                        - type
                        - available
                  claim_info:
                    type: object
                    properties:
                      factory_address:
                        type: string
                        pattern: ^0x[a-fA-F0-9]{40}$
                      salt:
                        type: integer
                    required:
                      - factory_address
                      - salt
                  nonce:
                    type: integer
                    minimum: 0
                  error:
                    type: string
                  error_category:
                    type: string
                  detail:
                    type: string
                required:
                  - success
                  - intent_id
                  - quote_id
                  - can_solve
                  - expiry
                additionalProperties: false
  /api/intent/execute:
    post:
      operationId: executeIntent
      summary: Execute a quoted intent
      description: "Submit the user's signed intent. Wallet-first: the EIP-712 signature in the body is the auth. Member/Mandate/Guest apply when their headers are present."
      tags:
        - intents
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                intent_id:
                  anyOf:
                    - type: string
                      pattern: ^xi_[0-9a-f]{32}$
                    - type: string
                      format: uuid
                quote_id:
                  anyOf:
                    - type: string
                      pattern: ^xq_[0-9a-f]{32}$
                    - type: string
                      format: uuid
                signature:
                  type: string
                  minLength: 1
                nonce:
                  type: integer
                  minimum: 0
                pull_signature:
                  type: string
                aztec_proof:
                  type: string
              required:
                - intent_id
                - quote_id
                - signature
                - nonce
      responses:
        "200":
          description: Intent submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  intent_id:
                    type: string
                  status:
                    type: string
                  tx_hash:
                    type: string
                  bridge_tx_hash:
                    type: string
                  receiving_tx_hash:
                    type: string
                  settlement_tx_hash:
                    type: string
                  settlement_chain_id:
                    type: integer
                  reconciling:
                    type: boolean
                  note_commitment:
                    type: string
                  stealth_address:
                    type: string
                  ephemeral_pub_key:
                    type: string
                  view_tag:
                    type: integer
                  error:
                    type: string
                required:
                  - success
                  - intent_id
                  - status
                additionalProperties: false
        "400":
          description: Validation error / bad state
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "401":
          description: Signature or presented credential invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "404":
          description: Intent not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "409":
          description: Intent already being executed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "502":
          description: Solver rejected / execution failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  intent_id:
                    type: string
                  status:
                    type: string
                  tx_hash:
                    type: string
                  bridge_tx_hash:
                    type: string
                  receiving_tx_hash:
                    type: string
                  settlement_tx_hash:
                    type: string
                  settlement_chain_id:
                    type: integer
                  reconciling:
                    type: boolean
                  note_commitment:
                    type: string
                  stealth_address:
                    type: string
                  ephemeral_pub_key:
                    type: string
                  view_tag:
                    type: integer
                  error:
                    type: string
                required:
                  - success
                  - intent_id
                  - status
                additionalProperties: false
  /api/intent/{id}:
    get:
      operationId: getIntent
      summary: Get intent record
      description: "Public: read-only intent record by its unguessable id."
      tags:
        - intents
      security: []
      parameters:
        - schema:
            type: string
            description: Intent id
          required: true
          name: id
          in: path
      responses:
        "200":
          description: Intent record
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  wallet_address:
                    type: string
                  status:
                    type: string
                  from_chain_id:
                    type: integer
                  to_chain_id:
                    type: integer
                  from_token:
                    type: string
                  to_token:
                    type: string
                  from_amount:
                    type: string
                  to_amount:
                    type:
                      - string
                      - "null"
                  quote_id:
                    type:
                      - string
                      - "null"
                  tier:
                    type:
                      - string
                      - "null"
                  fee_rate:
                    type:
                      - number
                      - "null"
                  settlement_type:
                    type:
                      - string
                      - "null"
                  aztec_note_hash:
                    type:
                      - string
                      - "null"
                  tx_hash:
                    type:
                      - string
                      - "null"
                  settlement_tx_hash:
                    type:
                      - string
                      - "null"
                  settlement_chain_id:
                    type:
                      - integer
                      - "null"
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  error:
                    type:
                      - string
                      - "null"
                required:
                  - id
                  - status
                  - from_chain_id
                  - to_chain_id
                  - from_token
                  - to_token
                  - from_amount
                  - to_amount
                  - quote_id
                  - tier
                  - fee_rate
                  - settlement_type
                  - aztec_note_hash
                  - tx_hash
                  - created_at
                  - updated_at
                  - error
                additionalProperties: false
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
  /api/intent/{id}/status:
    get:
      operationId: getIntentStatus
      summary: Poll intent status
      description: "Public: read-only status by the intent's unguessable id. `terminal` marks a settled state; `refund_reason` accompanies a `refunded` deposit route."
      tags:
        - intents
      security: []
      parameters:
        - schema:
            type: string
            description: Intent id
          required: true
          name: id
          in: path
      responses:
        "200":
          description: Current status
          content:
            application/json:
              schema:
                type: object
                properties:
                  intent_id:
                    type: string
                  status:
                    type: string
                  from_chain_id:
                    type: integer
                  to_chain_id:
                    type: integer
                  from_token:
                    type: string
                  to_token:
                    type: string
                  from_amount:
                    type: string
                  to_amount:
                    type: string
                  amount:
                    type: string
                  tx_hash:
                    type: string
                  settlement_tx_hash:
                    type: string
                  settlement_chain_id:
                    type: integer
                  receiving_tx_hash:
                    type: string
                  settlement_type:
                    type:
                      - string
                      - "null"
                  terminal:
                    type: boolean
                  error:
                    type:
                      - string
                      - "null"
                  refund_reason:
                    type: string
                  substatus:
                    type: string
                  substatus_message:
                    type: string
                  sending: {}
                  receiving: {}
                required:
                  - intent_id
                  - status
                  - from_chain_id
                  - to_chain_id
                  - from_token
                  - to_token
                  - from_amount
                  - settlement_type
                  - terminal
                additionalProperties: false
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
  /api/stealth/meta-address:
    get:
      operationId: getStealthMetaAddress
      summary: Lookup ERC-6538 stealth meta-address
      description: Returns `{found:false}` for an unregistered wallet or the full nested record when present. Never 404s.
      tags:
        - stealth
      parameters:
        - schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{40}$
            description: Wallet to look up
          required: true
          name: wallet
          in: query
      responses:
        "200":
          description: Meta-address record, or {found:false} when unregistered
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      found:
                        type: boolean
                        enum:
                          - false
                    required:
                      - found
                    additionalProperties: false
                  - type: object
                    properties:
                      found:
                        type: boolean
                        enum:
                          - true
                      metaAddress:
                        type: object
                        properties:
                          spendingPubKey:
                            type: string
                          viewingPubKey:
                            type: string
                          chainId:
                            type: integer
                        required:
                          - spendingPubKey
                          - viewingPubKey
                          - chainId
                        additionalProperties: false
                      encodedMetaAddress:
                        type: string
                      registryTxHash:
                        type:
                          - string
                          - "null"
                      createdAt:
                        type: string
                    required:
                      - found
                      - metaAddress
                      - encodedMetaAddress
                      - registryTxHash
                      - createdAt
                    additionalProperties: false
  /api/stealth/claim/prepare:
    post:
      operationId: claimStealthPrepare
      summary: Prepare a keyless stealth claim
      description: Phase 1 of the two-step keyless claim. Riddler builds the sponsored ERC-4337 UserOp and returns its hash for the recipient to sign locally; no private key crosses the wire. Gated by STEALTH_SETTLEMENT_LIVE (503 when off).
      tags:
        - stealth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                counterfactualAddress:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                recipientAddress:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
              required:
                - counterfactualAddress
                - recipientAddress
              additionalProperties: false
      responses:
        "200":
          description: UserOp hash to sign, with chain + stealth/counterfactual addresses
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  userOpHash:
                    type: string
                  chainId:
                    type: integer
                  stealthAddress:
                    type: string
                  counterfactualAddress:
                    type: string
                  error:
                    type: string
                required:
                  - success
                additionalProperties: false
        "400":
          description: Validation error / Riddler rejection
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "403":
          description: No claimable stealth settlement for that address (no indexed announcement)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "503":
          description: Stealth claims unavailable (flag off) or Riddler not configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
  /api/stealth/claim/submit:
    post:
      operationId: claimStealthSubmit
      summary: Submit a signed keyless stealth claim
      description: Phase 2 of the two-step keyless claim. Submit the recipient's signature over the prepared userOpHash; Riddler broadcasts the sponsored UserOp. Gated by STEALTH_SETTLEMENT_LIVE (503 when off).
      tags:
        - stealth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userOpHash:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{64}$
                signature:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{130}$
              required:
                - userOpHash
                - signature
              additionalProperties: false
      responses:
        "200":
          description: Broadcast tx hash + op hash (blockNumber once mined)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  txHash:
                    type: string
                  opHash:
                    type: string
                  blockNumber:
                    type: number
                  error:
                    type: string
                required:
                  - success
                additionalProperties: false
        "400":
          description: Validation error / Riddler rejection
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "403":
          description: No prepared claim for that userOpHash, or a different account prepared it
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "409":
          description: Claim already submitted (replay)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "410":
          description: Prepared claim expired; re-prepare
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
        "503":
          description: Stealth claims unavailable (flag off) or Riddler not configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                required:
                  - success
                  - error
                additionalProperties: false
  /api/settlement:
    get:
      operationId: getSettlements
      summary: List settlements for a wallet
      description: "Claimable + claimed settlements for the wallet, with stealth metadata where applicable. Auth: Member (JWT) or Guest (x402)."
      tags:
        - settlements
      parameters:
        - schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{40}$
            description: Wallet to list
          required: true
          name: wallet
          in: query
      responses:
        "200":
          description: Settlement list
          content:
            application/json:
              schema:
                type: object
                properties:
                  settlements:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - "null"
                        intentId:
                          type:
                            - string
                            - "null"
                        tokenAddress:
                          type:
                            - string
                            - "null"
                        amount:
                          type:
                            - string
                            - "null"
                        noteCommitment:
                          type:
                            - string
                            - "null"
                        status:
                          type:
                            - string
                            - "null"
                        sourceChainId:
                          type:
                            - number
                            - "null"
                        createdAt:
                          type:
                            - string
                            - "null"
                        claimedAt:
                          type:
                            - string
                            - "null"
                        claimTxHash:
                          type:
                            - string
                            - "null"
                        error:
                          type:
                            - string
                            - "null"
                        stealthAddress:
                          type:
                            - string
                            - "null"
                        ephemeralPubKey:
                          type:
                            - string
                            - "null"
                        viewTag:
                          type:
                            - number
                            - "null"
                        fromToken:
                          type:
                            - string
                            - "null"
                        toToken:
                          type:
                            - string
                            - "null"
                        fromAmount:
                          type:
                            - string
                            - "null"
                        toAmount:
                          type:
                            - string
                            - "null"
                      required:
                        - id
                        - intentId
                        - tokenAddress
                        - amount
                        - noteCommitment
                        - status
                        - sourceChainId
                        - createdAt
                        - claimedAt
                        - claimTxHash
                        - error
                        - stealthAddress
                        - ephemeralPubKey
                        - viewTag
                        - fromToken
                        - toToken
                        - fromAmount
                        - toAmount
                      additionalProperties: false
                required:
                  - settlements
                additionalProperties: false
  /api/prices:
    get:
      operationId: getPrices
      summary: Token prices (USD)
      description: Public, edge-cached (60s). A `{prices, live}` envelope; `live:false` means the worker served its static fallback after an upstream failure.
      tags:
        - prices
      security: []
      responses:
        "200":
          description: Symbol -> USD price map + live flag
          content:
            application/json:
              schema:
                type: object
                properties:
                  prices:
                    type: object
                    additionalProperties:
                      type: number
                  live:
                    type: boolean
                required:
                  - prices
                  - live
                additionalProperties: false
  /api/capabilities:
    get:
      operationId: getCapabilities
      summary: Solver capability matrix
      description: Public, edge-cached (300s). Proxy of Riddler /xochi/capabilities. The `{source, capabilities}` envelope is pinned; the inner body is a Riddler passthrough boundary.
      tags:
        - capabilities
      security: []
      responses:
        "200":
          description: Capability matrix envelope
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    enum:
                      - live
                      - fallback
                  capabilities: {}
                required:
                  - source
                additionalProperties: false
  /api/solver/stats:
    get:
      operationId: getSolverStats
      summary: Aggregate solver stats
      description: Public. Total + 30-day revenue, deposit count, projected APY.
      tags:
        - solver
      security: []
      responses:
        "200":
          description: Solver revenue stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  totalDeposited:
                    type: string
                  totalVaultDeposits:
                    type: string
                  depositCount:
                    type: integer
                  last30Days:
                    type: object
                    properties:
                      grossRevenue:
                        type: string
                      vaultDeposits:
                        type: string
                    required:
                      - grossRevenue
                      - vaultDeposits
                    additionalProperties: false
                  lastDeposit:
                    type:
                      - object
                      - "null"
                    properties:
                      amount:
                        type: string
                      vaultDeposit:
                        type: string
                      timestamp:
                        type: string
                    required:
                      - amount
                      - vaultDeposit
                      - timestamp
                    additionalProperties: false
                  projectedApy:
                    type: string
                required:
                  - success
                  - totalDeposited
                  - totalVaultDeposits
                  - depositCount
                  - last30Days
                  - lastDeposit
                  - projectedApy
                additionalProperties: false
webhooks: {}