Endpoint reference

Base URL: https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io. A bearer API key is required for /v1/account/*, /v1/referral/me*, POST /v1/orders/prepare, POST /v1/tx/submit, and for listing or deleting keys; everything else is public. The playground sends requests through the docs server, so a key you paste there passes through it. Amounts and prices are strings of 7-decimal fixed-point integers.

Markets

• GET /v1/markets/stats — Per-asset open interest (long / short / net, from the open-positions projection) and 24h traded volume (position_opened + realized position_closed / liquidated notional).
• GET /v1/markets — List all supported markets with current oracle prices.
• GET /v1/markets/{asset} — Single market detail with current oracle price.
• GET /v1/trades — Recent trades, newest first.
• GET /v1/candles — OHLC candles for an asset, oldest-first.

Oracle and prices

• GET /v1/oracle/prices — All supported asset prices read live from the Noeracle shim contract.
• GET /v1/markets/{asset}/price — Current oracle price for a single asset.
• POST /v1/oracle/heartbeat — Keeper status ingest (shared-secret header x-keeper-secret).
• GET /v1/oracle/health — Per-source oracle health: on-chain price age per asset + the keeper self-report.

Orders and transactions

• GET /v1/orders/open — Orders placed on the current market, folded to open / executed / cancelled, newest first.
• POST /v1/orders/prepare — Build an unsigned, simulated, prepared Soroban transaction for the requested trading op.
• POST /v1/tx/submit — Submit a signed Soroban transaction (base64 XDR) and poll until SUCCESS, FAILED, or pollTimeoutMs (default 30s).

Positions

• GET /v1/positions/open — Currently open positions on the market, optionally filtered by trader.
• GET /v1/adl/queue — Advisory auto-deleveraging queue for one asset (public): positive-pnl positions ranked by (pnl / collateral) × leverage, quintiles 1..5 (1 = first to be deleveraged if pool coverage fails).

Account

• GET /v1/account/me — Identity and tier of the authenticated API key holder.
• GET /v1/account/me/events — Decoded contract events whose payload references the authenticated owner address.
• GET /v1/account/me/positions — Open positions for the authenticated owner (from the indexer positions projection), plus the owner's position events (position_opened, position_closed, position_liquidated).
• GET /v1/account/me/orders — Order-related events for the authenticated owner.
• GET /v1/account/volume — Trailing 14-day traded notional for a wallet (public).
• GET /v1/account/shortfall — Claimable shortfall for a wallet (public, L0-3): USDC the vault still owes this trader from payouts it could not cover in full, plus the global repayment reserve.

Vaults

• GET /v1/vaults — List all vaults the indexer knows about (newest first).
• GET /v1/vaults/{id} — Detailed view of a single vault.
• GET /v1/vaults/{id}/trades — Leader open/close trade history for a vault, newest first.
• GET /v1/vaults/{id}/deposits — Deposit history for a vault, newest first.
• GET /v1/vaults/{id}/withdraws — Withdraw history for a vault, newest first.
• GET /v1/vaults/{id}/fee-claims — Leader profit-share claim history for a vault.

Referral

• GET /v1/referral/lookup — Resolve a referral code to its referrer (public).
• GET /v1/referral/info — Look up a referrer profile by Stellar address (public).
• GET /v1/referral/me — Returns the referral state of the authenticated owner — both their own referrer row (if any) and the binding they hold as a referee (if any).
• GET /v1/referral/me/trades — Trades the authenticated owner has earned referral fees on.
• GET /v1/referral/me/claims — Claim history for the authenticated owner as referrer.

Leaderboard

• GET /v1/leaderboard — Trader leaderboard from the indexer projections, ranked in SQL per deployment scope.
• GET /v1/leaderboard/rank — One trader's rank and row on the full board for a (scope, sort), looked up in the same snapshot the board pages slice, so it is always consistent with the pages and costs no extra scan.
• GET /v1/leaderboard/totals — Market wide headline totals (distinct traders, traded notional, trade count), aggregated in SQL over EVERY trader rather than the ranked page.

API keys

• GET /v1/keys/beta-status — Public — reports whether key issuance is currently gated to a closed-beta allowlist, and optionally whether the supplied address is on it.
• POST /v1/keys/challenge — Issue a one-time challenge string the wallet must sign before an API key can be created.
• GET /v1/keys — List all API keys owned by the authenticated key holder.
• POST /v1/keys — Exchange a signed challenge for a freshly minted API key + secret.
• DELETE /v1/keys/{keyId} — Revoke an API key.

Events and health

• GET /v1/health — Liveness + config probe.
• GET /v1/events — Raw decoded contract events captured by the indexer.