> ## 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. # Unified search across markets (events + users coming). > Strict full-text search backed by Postgres `websearch_to_tsquery`. Falls back to fuzzy trigram matching when the strict query returns nothing (toggle with `?fuzzy=false`). Response is a discriminated union per-result-type so adding events / users later is non-breaking. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/search/ 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 Most endpoints accept (and many require) an API key: ``` Authorization: Bearer aura_live_ ``` Mint a key by signing a one-time challenge with your Alephium wallet: ``` POST /v1/auth/challenge { "address": "..." } POST /v1/auth/keys { "address": "...", "publicKey": "...", "signature": "..." } ``` Reads are accessible anonymously with low IP-based rate limits; write endpoints (`/v1/tx/*`) always require a key. ## 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: - ApiKey: [] - {} tags: - name: Health description: Liveness + version info. - name: Auth description: Mint, list, and revoke API keys (wallet-signed). - 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. - name: Faucet description: Testnet faucet (proxied to indexer). externalDocs: description: Full Aura documentation (guides + interactive API reference) url: https://docs.aurabets.io paths: /v1/search/: get: tags: - Search summary: Unified search across markets (events + users coming). description: >- Strict full-text search backed by Postgres `websearch_to_tsquery`. Falls back to fuzzy trigram matching when the strict query returns nothing (toggle with `?fuzzy=false`). Response is a discriminated union per-result-type so adding events / users later is non-breaking. parameters: - schema: type: string minLength: 1 maxLength: 200 in: query name: q required: true description: 'Query string (websearch syntax: AND, OR, NOT, "phrases").' - schema: type: string in: query name: types required: false description: >- Comma-separated list of resource types to include. Allowed: market. Defaults to all. - schema: default: 20 type: integer minimum: 1 maximum: 50 in: query name: limit required: false - schema: default: true type: boolean in: query name: fuzzy required: false responses: '200': description: Default Response content: application/json: schema: type: object properties: results: type: array items: oneOf: - type: object properties: type: type: string enum: - market score: type: number description: >- Higher = more relevant. Engine-dependent scale; do not compare across types. data: type: object properties: id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Database id (stable, monotonic). marketAddress: type: string minLength: 30 maxLength: 80 pattern: >- ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz:]+$ description: >- Alephium address (base58, optional `:N` group suffix). question: type: string category: anyOf: - type: string - type: 'null' tags: type: array items: type: string description: >- Cross-cutting labels (e.g. ["nfl","superbowl"]). Empty if absent. creator: anyOf: - type: string minLength: 30 maxLength: 80 pattern: >- ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz:]+$ description: >- Alephium address (base58, optional `:N` group suffix). - type: 'null' resolved: type: boolean finalOutcome: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' volume: type: string description: >- Total traded volume in collateral base units (string, preserves precision). bestBidYes: anyOf: - type: integer minimum: 0 maximum: 1000 description: >- Price as integer ticks of 0.001 (0=No, 1000=Yes). - type: 'null' bestAskYes: anyOf: - type: integer minimum: 0 maximum: 1000 description: >- Price as integer ticks of 0.001 (0=No, 1000=Yes). - type: 'null' bestBidNo: anyOf: - type: integer minimum: 0 maximum: 1000 description: >- Price as integer ticks of 0.001 (0=No, 1000=Yes). - type: 'null' bestAskNo: anyOf: - type: integer minimum: 0 maximum: 1000 description: >- Price as integer ticks of 0.001 (0=No, 1000=Yes). - type: 'null' createdAt: type: string description: ISO-8601. metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' imageUrl: anyOf: - type: string - type: 'null' rules: anyOf: - type: string - type: 'null' resolutionSources: anyOf: - type: string - type: 'null' master: type: boolean masterQuestion: anyOf: - type: string - type: 'null' masterImage: anyOf: - type: string - type: 'null' linked: type: boolean proposalId: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: - id - marketAddress - question - category - tags - creator - resolved - finalOutcome - volume - bestBidYes - bestAskYes - bestBidNo - bestAskNo - createdAt - metadata additionalProperties: false required: - type - score - data additionalProperties: false facets: type: object properties: types: type: object propertyNames: type: string additionalProperties: type: integer minimum: 0 maximum: 9007199254740991 description: Hit count per resource type. required: - types additionalProperties: false fuzzyFallbackUsed: type: boolean description: >- True when the strict tsquery returned 0 hits and we fell back to trigram fuzzy matching. required: - results - facets - fuzzyFallbackUsed 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 '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 '500': 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: ApiKey: type: http scheme: bearer bearerFormat: aura_live_<32 char secret> description: API key obtained from POST /v1/auth/keys. ````