# Aura

> Decentralized prediction markets on Alephium. User docs, governance specs, and the public REST API.

## Docs

- [Combined "what does this wallet need to do right now" view.](https://docs.aura.markets/api-reference/account-actions/combined-"what-does-this-wallet-need-to-do-right-now"-view.md): Aggregates three categories that demand user action:   - **proposal-vote**: governance proposals in the active voting period that the wallet has not voted on.   - **dispute-commit**: oracle disputes currently in the commit window the wallet has not committed on.   - **dispute-reveal**: pending revea…
- [Reveal-relay queue for this wallet (salt redacted).](https://docs.aura.markets/api-reference/account-actions/reveal-relay-queue-for-this-wallet-salt-redacted.md): Returns rows the indexer is tracking from `pending_reveals` for this voter. The `salt` column is intentionally NOT exposed — leaking the salt before reveal would let observers reconstruct the still-secret vote choice from the on-chain commit hash.
- [List API keys for the caller's wallet.](https://docs.aura.markets/api-reference/auth/list-api-keys-for-the-callers-wallet.md): Returns every key (active + revoked) bound to the wallet that owns the calling key. Plaintext is never returned; only prefixes for identification.
- [Mint a one-time signing challenge for a wallet.](https://docs.aura.markets/api-reference/auth/mint-a-one-time-signing-challenge-for-a-wallet.md): Returns a short text the wallet must sign to prove ownership. The signed result is then submitted to `POST /v1/auth/keys` to mint a long-lived API key.
- [Mint an API key by submitting a signed challenge.](https://docs.aura.markets/api-reference/auth/mint-an-api-key-by-submitting-a-signed-challenge.md): Verifies the signature against the most recent unconsumed challenge for the address and returns the plaintext key. The plaintext is shown EXACTLY ONCE; the server stores only sha256(plaintext).
- [Revoke an API key.](https://docs.aura.markets/api-reference/auth/revoke-an-api-key.md): Soft-deletes the key (sets `revoked_at`). Revocation is immediate — the in-process auth cache TTL is short (≤30s) so any in-flight reuse stops within seconds.
- [Authentication](https://docs.aura.markets/api-reference/authentication.md): Mint an API key by signing a one-time challenge with your Alephium wallet.
- [Build-tx Flow](https://docs.aura.markets/api-reference/build-tx-flow.md): How non-custodial transaction building works under `/v1/tx/*`.
- [List all known market categories with counts.](https://docs.aura.markets/api-reference/categories/list-all-known-market-categories-with-counts.md): Counts reflect tradeable markets only (unresolved + master leg of any linked-market group). Pass the `slug` to /v1/markets?category=… to filter.
- [Get the dispute state for a specific market.](https://docs.aura.markets/api-reference/disputes/get-the-dispute-state-for-a-specific-market.md)
- [List disputed markets, with derived phase.](https://docs.aura.markets/api-reference/disputes/list-disputed-markets-with-derived-phase.md): Filter by `?phase=` (commit-open / reveal-open / awaiting-finalization / finalized) to scope to actionable rows. The `phase` is computed server-side from the raw commit/reveal timestamps + finalised flag, so every consumer sees the same answer.
- [List revealed votes on a disputed market.](https://docs.aura.markets/api-reference/disputes/list-revealed-votes-on-a-disputed-market.md): Returns the `dispute_votes` rows for the latest `vote_round` of the dispute on this market. Pre-reveal commits are NOT exposed (that data leaks the still-secret vote).
- [Create a new proposal draft for the calling wallet.](https://docs.aura.markets/api-reference/drafts/create-a-new-proposal-draft-for-the-calling-wallet.md): Drafts are wallet-private; the API key's `ownerAddress` is used as `user_address`. Every field is optional — drafts can be partially filled at any point.
- [Delete a draft.](https://docs.aura.markets/api-reference/drafts/delete-a-draft.md)
- [Fetch a single draft by id (must be owned by the calling wallet).](https://docs.aura.markets/api-reference/drafts/fetch-a-single-draft-by-id-must-be-owned-by-the-calling-wallet.md)
- [List the calling wallet's drafts.](https://docs.aura.markets/api-reference/drafts/list-the-calling-wallets-drafts.md): Newest first. No pagination yet — the practical cap on personal drafts is small.
- [Update fields on an existing draft.](https://docs.aura.markets/api-reference/drafts/update-fields-on-an-existing-draft.md): Partial update — only the fields present in the request body are written. Returns the full draft after the update applies.
- [Errors](https://docs.aura.markets/api-reference/errors.md): Standard error envelope and HTTP status codes used across the API.
- [Get one event with its full leg array.](https://docs.aura.markets/api-reference/events/get-one-event-with-its-full-leg-array.md): The `id` is the master market id (also surfaced as `event.id` on /v1/events). Always returns legs expanded — for a leg-less master view, query /v1/markets/:address directly using the master's address.
- [List events (linked-market groups).](https://docs.aura.markets/api-reference/events/list-events-linked-market-groups.md): Each event is the master row of a linked-market group. `?withLegs=true` expands the full leg array on every event in the response (one extra DB query — keep it off when rendering an index page).
- [Check faucet eligibility for an address.](https://docs.aura.markets/api-reference/faucet/check-faucet-eligibility-for-an-address.md): Returns when the address last claimed and when it can claim again.
- [Claim testnet ALPH + USDT + AURA.](https://docs.aura.markets/api-reference/faucet/claim-testnet-alph-+-usdt-+-aura.md): Sends a one-time bundle of test tokens to `address`. Rate-limited per address AND per IP at 24h. Proxied to the indexer service which holds the faucet wallet key.
- [Liveness probe.](https://docs.aura.markets/api-reference/health/liveness-probe.md)
- [Introduction](https://docs.aura.markets/api-reference/introduction.md): Public REST API for Aura — markets, prices, vault, oracle, governance, and unsigned tx builders.
- [Top traders by composite (volume + win-ratio) score.](https://docs.aura.markets/api-reference/leaderboard/top-traders-by-composite-volume-+-win-ratio-score.md): Backed by the `user_leaderboard{,_last_month,_total}` materialized views. Score = volume_rel * (0.7 + 0.3 * win_ratio); rank is `dense_rank()` over score DESC. Refresh cadence is owned by the indexer — clients should not assume sub-second freshness.
- [Composite-score trending markets.](https://docs.aura.markets/api-reference/markets/composite-score-trending-markets.md): Top markets by a transparent blended score (volume × recency × tightness). The component scores are returned alongside each market so a UI can render "why is this trending" copy and integrators can audit the ranking.
- [Get a market by address.](https://docs.aura.markets/api-reference/markets/get-a-market-by-address.md)
- [List markets with full filter / sort / cursor / facet support.](https://docs.aura.markets/api-reference/markets/list-markets-with-full-filter-sort-cursor-facet-support.md): The discovery workhorse. Use `?q=` for full-text search, `?category=` + `?tags=` for filtering, `?sort=` + `?order=` for ordering, and `?cursor=` for stable deep pagination (offset paging via `?page=` is also supported but not recommended past page 100). Pass `?facets=true` to get category / tag / s…
- [Markets in the same linked-market group.](https://docs.aura.markets/api-reference/markets/markets-in-the-same-linked-market-group.md): Returns the master market + every leg in the linked group this market belongs to. 404s for standalone markets (no group exists) — call `/v1/markets/:address` instead. Use `/v1/events/:id` if you have the master id directly; this endpoint is for the "give me siblings of THIS market" lookup.
- [Build an unsigned OptimisticOracle.commitVote transaction.](https://docs.aura.markets/api-reference/oracle-votes/build-an-unsigned-optimisticoraclecommitvote-transaction.md): Posts the commit hash on-chain. The full reveal payload should ALSO be posted to /v1/oracle/pending-reveal so the indexer's reveal-automation can dispatch the reveal during the reveal window.
- [Build an unsigned OptimisticOracle.disputeOutcome transaction.](https://docs.aura.markets/api-reference/oracle-votes/build-an-unsigned-optimisticoracledisputeoutcome-transaction.md): Locks `bondAmount` USDT to challenge the proposed outcome.
- [Build an unsigned OptimisticOracle.revealVote transaction.](https://docs.aura.markets/api-reference/oracle-votes/build-an-unsigned-optimisticoraclerevealvote-transaction.md): Manually reveal a previously-committed vote. Most callers should rely on the indexer's reveal-automation (post the payload to /v1/oracle/pending-reveal); this endpoint is for self-service reveals.
- [Build an unsigned OptimisticOracle.submitOutcome transaction.](https://docs.aura.markets/api-reference/oracle-votes/build-an-unsigned-optimisticoraclesubmitoutcome-transaction.md): Locks `bondAmount` USDT alongside the proposed outcome. Match the on-chain bond size.
- [Submit a pending reveal payload after committing a dispute vote.](https://docs.aura.markets/api-reference/oracle-votes/submit-a-pending-reveal-payload-after-committing-a-dispute-vote.md): Right after a user signs `commitVote`, post the matching `{salt, voteChoice}` here. The indexer's reveal-automation will submit the on-chain `revealVote` tx during the reveal window. Authentication is implicit — the body must hash to the on-chain commit hash.
- [Aggregated order book for both outcomes.](https://docs.aura.markets/api-reference/orderbook/aggregated-order-book-for-both-outcomes.md): Returns price-level aggregates for both YES and NO sides in a single response. Bids are highest-price-first; asks are lowest-price-first. The top-level `bestBid*` / `bestAsk*` fields summarise the touch.
- [Recent trades (executed fills) for a market.](https://docs.aura.markets/api-reference/orderbook/recent-trades-executed-fills-for-a-market.md): Paginated stream of `order_fills`, newest first. Cursor pagination recommended for deep history (offset paging supported via `?page=` for compat).
- [Build an unsigned CancelOrder transaction.](https://docs.aura.markets/api-reference/orders/build-an-unsigned-cancelorder-transaction.md)
- [Build an unsigned PlaceLimitOrder transaction.](https://docs.aura.markets/api-reference/orders/build-an-unsigned-placelimitorder-transaction.md): Returns an unsigned tx the client can sign. For BUY orders the response includes the exact USDT collateral the user must hold (price × quantity / 1000 + 2.5% fee).
- [Build an unsigned PlaceMarketOrder transaction.](https://docs.aura.markets/api-reference/orders/build-an-unsigned-placemarketorder-transaction.md): Market orders cross the book at the best available price. `expectedPrice` (optional) tightens the pre-locked collateral; if omitted, MAX_ORDER_PRICE is used (worst case) and the contract refunds unused collateral at fill time.
- [Bucketed price history for a market.](https://docs.aura.markets/api-reference/prices/bucketed-price-history-for-a-market.md): Defers to the `get_market_price_history` PL/pgSQL helper — bucket size depends on the requested `range`: 1m for 1H, 6m for 6H, 5m for 1D, 30m for 1W, 3h for 1M, 1d for ALL. Gaps are filled with the last-known price so the series renders smoothly in line charts.
- [Latest price snapshot for a market.](https://docs.aura.markets/api-reference/prices/latest-price-snapshot-for-a-market.md): Returns the most recent `(yesPrice, priceTimestamp)` pair from `market_prices`. `noPrice` is computed as `1 - yesPrice`. Both prices are returned in [0, 1] probability.
- [Build an unsigned MarketFactory.linkProposals transaction (admin-flavoured).](https://docs.aura.markets/api-reference/proposals/build-an-unsigned-marketfactorylinkproposals-transaction-admin-flavoured.md): Groups already-on-chain proposals into one event with a master question + image. **For most users, prefer POST /v1/tx/factory/propose-linked-market** — it proposes all legs AND links them in a single signed tx, which is the right UX for "I want to create a multi-outcome market". This endpoint is the…
- [Build an unsigned MarketFactory.parlayDeposit transaction.](https://docs.aura.markets/api-reference/proposals/build-an-unsigned-marketfactoryparlaydeposit-transaction.md): Locks `amount` USDT and submits a parlay across multiple markets. `marketIds` must be pre-encoded as hex per the contract's expected format.
- [Build an unsigned multi-leg market proposal (one tx, N legs).](https://docs.aura.markets/api-reference/proposals/build-an-unsigned-multi-leg-market-proposal-one-tx-n-legs.md): The right primitive for any market with more than two outcomes — sports games, multi-candidate races, conditional markets. Provide an array of `legs[]` with their individual question/imageUrl/metadata + the shared masterQuestion / category / rules / sources. The endpoint picks the right ProposeAndSu…
- [Build an unsigned ProposeAndSubmitMarket transaction (single-leg).](https://docs.aura.markets/api-reference/proposals/build-an-unsigned-proposeandsubmitmarket-transaction-single-leg.md): Submits one binary (yes/no) market proposal for governance review in a single tx. For a multi-outcome event (e.g. "who wins this game?" with 4 candidates), use POST /v1/tx/factory/propose-linked-market instead — it bundles all legs into one signed tx. Strings are accepted as plain text and hex-encod…
- [Dry-run validate a market proposal before signing.](https://docs.aura.markets/api-reference/proposals/dry-run-validate-a-market-proposal-before-signing.md): Pure validator — no chain, no DB, no signer. Returns a list of issues + per-field UTF-8 byte sizes + the estimated ALPH attached to the eventual tx. Use this from a "preview" screen so users see "your proposal looks good" (or what to fix) before being asked to sign anything.
- [Rate Limits](https://docs.aura.markets/api-reference/rate-limits.md): Per-IP and per-key request budgets, with standard `RateLimit-*` response headers.
- [Unified search across markets (events + users coming).](https://docs.aura.markets/api-reference/search/unified-search-across-markets-events-+-users-coming.md): 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.
- [List tags with market counts.](https://docs.aura.markets/api-reference/tags/list-tags-with-market-counts.md): Returns the full tag list (or a substring-filtered subset) with the count of tradeable markets each tag is attached to. Pass `?category=` to scope the counts to one category.
- [Open + settled positions for a wallet.](https://docs.aura.markets/api-reference/users/open-+-settled-positions-for-a-wallet.md)
- [Open / filled / cancelled orders for a wallet.](https://docs.aura.markets/api-reference/users/open-filled-cancelled-orders-for-a-wallet.md): `status=open` filters to active book orders (not cancelled, not fully filled). `status=filled` returns orders where filled >= quantity. `status=cancelled` returns cancelled orders. `status=all` returns everything.
- [Parlay tickets for a wallet.](https://docs.aura.markets/api-reference/users/parlay-tickets-for-a-wallet.md)
- [Public profile + lifetime trading stats for a wallet.](https://docs.aura.markets/api-reference/users/public-profile-+-lifetime-trading-stats-for-a-wallet.md): Returns the trading + display columns from `users`. AI-quota, passkey, and vault-template columns are intentionally hidden — they are internal to the FE. Returns a synthesised zero-volume profile for never-traded addresses (no 404).
- [Build an unsigned vault deposit transaction (lock AURA).](https://docs.aura.markets/api-reference/vault/build-an-unsigned-vault-deposit-transaction-lock-aura.md)
- [Build an unsigned vault unlock-request transaction.](https://docs.aura.markets/api-reference/vault/build-an-unsigned-vault-unlock-request-transaction.md): Starts the unlock timelock (default 7 days). Withdraw only succeeds after the timelock elapses.
- [Build an unsigned vault withdraw transaction (after unlock timelock).](https://docs.aura.markets/api-reference/vault/build-an-unsigned-vault-withdraw-transaction-after-unlock-timelock.md)
- [Build an unsigned Voting.vote transaction.](https://docs.aura.markets/api-reference/vote/build-an-unsigned-votingvote-transaction.md): Casts a governance vote on a proposal. Voting weight is read from on-chain stake.
- [Current governance voting period state.](https://docs.aura.markets/api-reference/voting/current-governance-voting-period-state.md): Returns the active voting period (one window during which proposals are votable) plus a convenience `isOpen` flag and the server `now`. Clients should use `now` (not their local clock) for any countdown UI to avoid skew complaints from end-users.
- [Get a single proposal by id.](https://docs.aura.markets/api-reference/voting/get-a-single-proposal-by-id.md)
- [List governance proposals.](https://docs.aura.markets/api-reference/voting/list-governance-proposals.md): Filter by `status`, `category`, `proposer`, or `activePeriodOnly=true`. Use `?sort=` to order by created-at, vote-count, or unique-voters. Cursor pagination via `?cursor=`; offset paging via `?page=` is supported but not recommended past page 100.
- [List votes cast on a proposal.](https://docs.aura.markets/api-reference/voting/list-votes-cast-on-a-proposal.md)
- [Bridging to Aura](https://docs.aura.markets/getting-started/bridging.md): Move USDT from Ethereum or BSC into Aura via the integrated Wormhole bridge.
- [Connecting to Aura](https://docs.aura.markets/getting-started/connecting.md): Two ways to get on Aura: a passkey wallet (recommended) or the Alephium browser extension.
- [Passkey Wallets](https://docs.aura.markets/getting-started/passkeys.md): A passwordless, non-custodial wallet secured by your device's biometrics.
- [Outcome Voting](https://docs.aura.markets/governance/outcome-voting.md): How disputed markets get resolved by neutral $AURA stakers via commit/reveal.
- [Proposal Voting](https://docs.aura.markets/governance/proposal-voting.md): How new market proposals are reviewed and approved by the community.
- [Welcome to Aura](https://docs.aura.markets/index.md): Decentralized prediction markets on Alephium — trade outcomes, propose markets, govern resolution.
- [Creating Markets](https://docs.aura.markets/markets/creating-markets.md): How to propose a new prediction market on Aura.
- [Resolution & Disputes](https://docs.aura.markets/markets/resolution-and-disputes.md): How Aura's optimistic oracle settles markets, and how the commit/reveal vote handles disputes.
- [Rewards & Incentives](https://docs.aura.markets/markets/rewards-and-incentives.md): Creator fee shares, dispute voter rewards, and the liquidity rewards program.
- [Trading on Aura](https://docs.aura.markets/markets/trading.md): Aura uses a central limit order book. Place market or limit orders, build parlays, and earn from spreads.
- [Introduction to Aura](https://docs.aura.markets/overview/introduction.md): What Aura is, who it's for, and what makes it different.
- [Roadmap](https://docs.aura.markets/overview/roadmap.md): Where Aura has been and where it's going.
- [Why Alephium?](https://docs.aura.markets/overview/why-alephium.md): Alephium's architecture is the right foundation for prediction markets.
- [Contact & Community](https://docs.aura.markets/support/contact.md): Where to ask questions, get support, and stay in the loop.
- [Frequently Asked Questions](https://docs.aura.markets/support/faq.md): Quick answers to the most common questions about Aura.
- [Alephium (ALPH)](https://docs.aura.markets/tokens/alph.md): How ALPH is used on Aura — and why you don't need to hold it.
- [$AURA Token](https://docs.aura.markets/tokens/aura.md): Native vaulting and governance token for the Aura protocol.
- [Staking & Vaulting $AURA](https://docs.aura.markets/tokens/staking.md): Stake $AURA to unlock tier benefits, earn voting power, and put skin in the oracle.
- [Tier Structure](https://docs.aura.markets/tokens/tier-structure.md): Stake $AURA to unlock tiers — voting power, fee shares, and proposal rights scale with your tier.
- [Binary Market Best Practices](https://docs.aura.markets/tutorials/binary-market-best-practices.md): How to write clear, resolvable YES/NO markets.
- [Categorical Market Best Practices](https://docs.aura.markets/tutorials/categorical-market-best-practices.md): How to write multi-option markets that resolve cleanly.
- [Maximizing Your Tier Benefits](https://docs.aura.markets/tutorials/maximizing-tier-benefits.md): Get the most out of your $AURA stake — voting power, fee shares, and passive income.
- [Strategies for Prediction Markets](https://docs.aura.markets/tutorials/strategies.md): Research, diversify, monitor — and capitalize on mispricing.
- [User Tutorials](https://docs.aura.markets/tutorials/user-tutorials.md): Step-by-step guides to get going on Aura quickly.
- [Voting on Disputes](https://docs.aura.markets/tutorials/voting-on-disputes.md): Step-by-step walkthrough of the commit/reveal voting flow on a disputed market.

## OpenAPI Specs

- [openapi](https://docs.aura.markets/api-reference/openapi.json)