> ## Documentation Index > Fetch the complete documentation index at: https://docs.aura.markets/llms.txt > Use this file to discover all available pages before exploring further. # Sign in / register by submitting a signed challenge. > Verifies the passkey assertion against the most recent unconsumed challenge for the address, creates or refreshes the account row, and sets an HttpOnly session cookie bound to the verified wallet. The CSRF token is returned in the body (echo it back in the `x-csrf-token` header on subsequent mutating requests) and also set as a readable cookie. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/auth/session openapi: 3.1.0 info: title: Aura API description: >- Public REST API for Aura — prediction markets on Alephium. This API exposes everything a user can see or do in the app: markets, prices, orderbook, trades, vault state, oracle and governance, plus build-tx endpoints that return unsigned transactions for the client to sign with its own wallet. Interactive reference: https://docs.aurabets.io/api-reference/introduction ## Discovery Built for integrators, not for lazy implementers: - **Faceted lists** — every list endpoint accepts `?facets=true` and returns category / tag / status counts in the same response, so a UI can render filter chips without a second request. - **Cursor pagination** — stable across inserts and fast at depth. Offset paging via `?page=` is still supported for compat. - **Rich filters** — `?q=`, `?category=`, `?tags=`, `?status=`, `?creator=`, `?minVolume=` on `/v1/markets`. Tag matching is AND (all listed tags must be present). - **Sortable** — `?sort=created-at|volume|best-bid-yes|recently-traded` with `?order=asc|desc`. Use `/v1/trending` for the composite-score sort. - **Field projection** — `?fields=id,question,bestBidYes` trims the wire weight for thin clients. - **Unified search** — `/v1/search?q=` runs a strict tsquery first with a fuzzy trigram fallback when nothing matches; result type is a discriminated union so adding events / users later is non-breaking. - **Transparent trending** — `/v1/trending` returns the full algorithm + per-market component scores so the ranking is auditable. - **Categories + tags as first-class** — `/v1/categories` and `/v1/tags` enumerate the taxonomy with market counts. ## Authentication Aura uses passkey-backed account sessions delivered as an HttpOnly cookie. Sign in by signing a one-time challenge with your passkey: ``` POST /v1/auth/challenge { "address": "..." } POST /v1/auth/session { "address": "...", "publicKey": "...", "signature": "...", "passkey": { ... } } ``` The `session` call sets the `aura_session` cookie and returns a CSRF token; send it back in the `x-csrf-token` header on every mutating request. `POST /v1/auth/logout` clears the session. Reads are accessible anonymously with low IP-based rate limits; write endpoints (`/v1/tx/*`, social writes) require a valid session. ## Rate limits | Tier | Reads (req/min) | Writes (req/min) | |-----------|----------------:|-----------------:| | Anonymous | 100000 per IP | 100000 per IP | | API key | 100000 per key | 100000 per key | Standard `RateLimit-*` response headers are returned on every request (IETF `draft-ietf-httpapi-ratelimit-headers`). ## Write endpoints Aura is non-custodial — the API never holds private keys. Endpoints under `/v1/tx/*` return an *unsigned* transaction that the caller must sign with its own wallet (passkey, mobile wallet, hardware wallet, etc.) and submit to an Alephium node. A typical "place order" flow: 1. `POST /v1/tx/markets/{address}/orders` → server returns `{ unsignedTx, gasEstimate, ... }`. 2. Wallet signs `unsignedTx`. 3. Wallet submits the signed tx to any Alephium node. version: 0.1.0 license: name: MIT contact: name: Aura url: https://docs.aurabets.io servers: - url: / description: this server security: - SessionCookie: [] - {} tags: - name: Health description: Liveness + version info. - name: Auth description: Passkey account sessions (sign in, sign out). - name: Markets description: Browse and look up prediction markets. - name: Categories description: Top-level market taxonomy with counts. - name: Tags description: Free-form market tags with counts. - name: Events description: Linked-market groups (multi-leg events). - name: Search description: Full-text + fuzzy search across markets. - name: Orderbook description: Live order book + recent fills. - name: Prices description: Latest prices and historical price series. - name: Orders description: Build unsigned tx to place / cancel orders. - name: Vault description: AURA token vault — build unsigned deposit / unlock / withdraw txs. - name: Disputes description: Optimistic oracle disputes — read-side state and votes. - name: Oracle votes description: Build unsigned oracle txs (submit / dispute / commit / reveal). - name: Voting description: Governance proposals + voting period state. - name: Vote description: Build unsigned governance vote tx. - name: Proposals description: Validate + build market-proposal txs (single-leg, linked, parlay). - name: Drafts description: Wallet-private market-proposal drafts (never on chain). - name: Users description: Wallet-scoped reads — profile, positions, orders, parlays. - name: Account actions description: Aggregated "what does this wallet need to do" views. - name: Leaderboard description: Top traders by composite score. externalDocs: description: Full Aura documentation (guides + interactive API reference) url: https://docs.aurabets.io paths: /v1/auth/session: post: tags: - Auth summary: Sign in / register by submitting a signed challenge. description: >- Verifies the passkey assertion against the most recent unconsumed challenge for the address, creates or refreshes the account row, and sets an HttpOnly session cookie bound to the verified wallet. The CSRF token is returned in the body (echo it back in the `x-csrf-token` header on subsequent mutating requests) and also set as a readable cookie. requestBody: required: true content: application/json: schema: type: object properties: address: type: string minLength: 30 maxLength: 80 pattern: >- ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz:]+$ description: Alephium address (base58, optional `:N` group suffix). publicKey: type: string pattern: ^(0x)?[0-9a-fA-F]+$ description: >- Public key whose hash equals `address` (33-byte compressed, hex). signature: type: string pattern: ^(0x)?[0-9a-fA-F]+$ description: >- Signature produced by `signMessage(challenge, "alephium")`. The Alephium WebAuthn blob for passkey wallets. keyType: default: gl-webauthn description: >- Wallet key type. `gl-webauthn` = passkey (the only type the app uses). type: string enum: - default - gl-webauthn passkey: description: >- Passkey credential metadata, persisted to the account row on first sign-in. type: object properties: credentialId: type: string minLength: 1 maxLength: 1024 username: type: string minLength: 1 maxLength: 120 publicKeyHex: type: string minLength: 1 maxLength: 1024 publicKeyCompressed: type: string minLength: 1 maxLength: 1024 createdAt: type: string required: - credentialId - username - publicKeyHex - publicKeyCompressed challenge: description: >- The exact challenge text the assertion signed. Send this for passkey login (where the challenge was issued without an address); the server consumes it by text. Omit it when the challenge was issued for a known address (it is then consumed by address). type: string refererAddress: description: >- Optional referrer wallet, captured once on first registration. Ignored if it equals the caller or does not exist. anyOf: - type: string minLength: 30 maxLength: 80 pattern: >- ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz:]+$ description: Alephium address (base58, optional `:N` group suffix). - type: 'null' required: - address - publicKey - signature responses: '200': description: Default Response content: application/json: schema: type: object properties: address: type: string minLength: 30 maxLength: 80 pattern: >- ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz:]+$ description: Alephium address (base58, optional `:N` group suffix). csrf: type: string description: >- CSRF token — send as the x-csrf-token header on mutating requests. created: type: boolean description: true when this call created a new account row. required: - address - csrf - created additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code (snake_case). message: type: string description: Human-readable error message. details: {} required: - code - message additionalProperties: false required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code (snake_case). message: type: string description: Human-readable error message. details: {} required: - code - message additionalProperties: false required: - error additionalProperties: false '429': description: Default Response content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code (snake_case). message: type: string description: Human-readable error message. details: {} required: - code - message additionalProperties: false required: - error additionalProperties: false '503': description: Default Response content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code (snake_case). message: type: string description: Human-readable error message. details: {} required: - code - message additionalProperties: false required: - error additionalProperties: false components: securitySchemes: SessionCookie: type: apiKey in: cookie name: aura_session description: >- HttpOnly session cookie set by POST /v1/auth/session. Mutating requests must also send the CSRF token (returned by that call) in the x-csrf-token header. ````