# Noether Docs

> User guides, API reference and protocol documentation for Noether, the decentralized perpetual futures exchange on Stellar.
- Guides: Trade, earn and refer from the web app
  - [Overview](https://docs.noether.exchange/guides): Where to start as a trader, depositor, vault leader or referrer on the Noether testnet app, with each guide in one line.
  - [Getting started](https://docs.noether.exchange/guides/getting-started): Install a Stellar wallet, activate it, claim test USDC from the Faucet, open a first position and close it again, in about ten minutes.
  - [Trading](https://docs.noether.exchange/guides/trading): The trader's manual for the testnet app: pairs and limits, every order type, isolated and cross margin, fee tiers, funding and how liquidation pays out.
  - [Earn: protocol vault](https://docs.noether.exchange/guides/vault): For depositors: how the protocol vault backs every trade, how to deposit USDC for NOE and withdraw again, the fees and cooldown, and the risk you underwrite.
  - [Trader vaults](https://docs.noether.exchange/guides/trader-vaults): Copy-trading vaults on the Vaults page: how depositors buy shares and withdraw, how leaders create, trade and get paid, and the on-chain rules for both.
  - [Referrals](https://docs.noether.exchange/guides/referrals): Create an on-chain referral code, share your link, bind referees, and claim your 10% share of their trading fees in USDC while they save 4% on every trade.
  - [FAQ](https://docs.noether.exchange/guides/faq): Short answers on test funds, wallets, regions, failed trades, fees, funding, liquidation, vault withdrawals, the closed beta, resets and where to get help.
- Developers: REST and WebSocket API, SDKs, errors
  - [Overview](https://docs.noether.exchange/developers): Where the Noether gateway lives, what needs an API key, how rate limits and regional rules apply, and where each reference page is.
  - [Authentication](https://docs.noether.exchange/developers/authentication): How to turn a Stellar wallet signature into a gateway API key, send it with the required timestamp header, and manage or revoke keys.
  - REST API
    - [Overview](https://docs.noether.exchange/developers/rest-api): Base URL, auth badges, precision and timestamp conventions, page-size limits, error shapes and rate limits shared by every REST endpoint.
    - [Markets and market data](https://docs.noether.exchange/developers/rest-api/markets): The market list, per-asset detail, open interest and capacity stats, recent trades, OHLC candles and the leaderboard, all without a key.
    - [Oracle and prices](https://docs.noether.exchange/developers/rest-api/oracle): Read the on-chain Noeracle price for one asset or all sixteen, check oracle and keeper health, and learn the staleness rules that gate trading.
    - [Account](https://docs.noether.exchange/developers/rest-api/account): The key-scoped endpoints for your identity, events, open positions and order history, plus the public 14-day volume and shortfall lookups.
    - [Positions](https://docs.noether.exchange/developers/rest-api/positions): Open positions across the venue or for one trader, each with its advisory ADL quintile, plus the per-asset auto-deleveraging queue.
    - [Orders and transactions](https://docs.noether.exchange/developers/rest-api/trading): The prepare, sign and submit flow behind every API trade, all ten operations, submit statuses and retries, and the public open-orders feed.
    - [Vaults](https://docs.noether.exchange/developers/rest-api/vaults): Trader Vault marketplace rows with computed aggregates, single-vault detail with full NAV, and the trade, deposit, withdraw and fee-claim feeds.
    - [Referral](https://docs.noether.exchange/developers/rest-api/referral): Resolve referral codes, read any wallet's referrer profile and binding, and pull your own referred trades and claims with an API key.
    - [Keys, events and health](https://docs.noether.exchange/developers/rest-api/system): The five API-key lifecycle endpoints, the raw decoded contract event feed, and the health probe that echoes the gateway's resolved contract addresses.
  - Endpoint reference
    - [Endpoint reference](https://docs.noether.exchange/developers/reference): Every gateway route, generated from the live OpenAPI spec, with request samples in curl, JavaScript and Python and a playground you can run against testnet.
    - Markets
      - [GET /v1/markets/stats](https://docs.noether.exchange/developers/reference/markets/get-markets-stats)
      - [GET /v1/markets](https://docs.noether.exchange/developers/reference/markets/get-markets)
      - [GET /v1/markets/{asset}](https://docs.noether.exchange/developers/reference/markets/get-markets-by-asset)
      - [GET /v1/trades](https://docs.noether.exchange/developers/reference/markets/get-trades)
      - [GET /v1/candles](https://docs.noether.exchange/developers/reference/markets/get-candles)
    - Oracle and prices
      - [GET /v1/oracle/prices](https://docs.noether.exchange/developers/reference/oracle/get-oracle-prices)
      - [GET /v1/markets/{asset}/price](https://docs.noether.exchange/developers/reference/oracle/get-markets-by-asset-price)
      - [POST /v1/oracle/heartbeat](https://docs.noether.exchange/developers/reference/oracle/post-oracle-heartbeat)
      - [GET /v1/oracle/health](https://docs.noether.exchange/developers/reference/oracle/get-oracle-health)
    - Orders and transactions
      - [GET /v1/orders/open](https://docs.noether.exchange/developers/reference/trading/get-orders-open)
      - [POST /v1/orders/prepare](https://docs.noether.exchange/developers/reference/trading/post-orders-prepare)
      - [POST /v1/tx/submit](https://docs.noether.exchange/developers/reference/trading/post-tx-submit)
    - Positions
      - [GET /v1/positions/open](https://docs.noether.exchange/developers/reference/positions/get-positions-open)
      - [GET /v1/adl/queue](https://docs.noether.exchange/developers/reference/positions/get-adl-queue)
    - Account
      - [GET /v1/account/me](https://docs.noether.exchange/developers/reference/account/get-account-me)
      - [GET /v1/account/me/events](https://docs.noether.exchange/developers/reference/account/get-account-me-events)
      - [GET /v1/account/me/positions](https://docs.noether.exchange/developers/reference/account/get-account-me-positions)
      - [GET /v1/account/me/orders](https://docs.noether.exchange/developers/reference/account/get-account-me-orders)
      - [GET /v1/account/volume](https://docs.noether.exchange/developers/reference/account/get-account-volume)
      - [GET /v1/account/shortfall](https://docs.noether.exchange/developers/reference/account/get-account-shortfall)
    - Vaults
      - [GET /v1/vaults](https://docs.noether.exchange/developers/reference/vaults/get-vaults)
      - [GET /v1/vaults/{id}](https://docs.noether.exchange/developers/reference/vaults/get-vaults-by-id)
      - [GET /v1/vaults/{id}/trades](https://docs.noether.exchange/developers/reference/vaults/get-vaults-by-id-trades)
      - [GET /v1/vaults/{id}/deposits](https://docs.noether.exchange/developers/reference/vaults/get-vaults-by-id-deposits)
      - [GET /v1/vaults/{id}/withdraws](https://docs.noether.exchange/developers/reference/vaults/get-vaults-by-id-withdraws)
      - [GET /v1/vaults/{id}/fee-claims](https://docs.noether.exchange/developers/reference/vaults/get-vaults-by-id-fee-claims)
    - Referral
      - [GET /v1/referral/lookup](https://docs.noether.exchange/developers/reference/referral/get-referral-lookup)
      - [GET /v1/referral/info](https://docs.noether.exchange/developers/reference/referral/get-referral-info)
      - [GET /v1/referral/me](https://docs.noether.exchange/developers/reference/referral/get-referral-me)
      - [GET /v1/referral/me/trades](https://docs.noether.exchange/developers/reference/referral/get-referral-me-trades)
      - [GET /v1/referral/me/claims](https://docs.noether.exchange/developers/reference/referral/get-referral-me-claims)
    - Leaderboard
      - [GET /v1/leaderboard](https://docs.noether.exchange/developers/reference/leaderboard/get-leaderboard)
      - [GET /v1/leaderboard/rank](https://docs.noether.exchange/developers/reference/leaderboard/get-leaderboard-rank)
      - [GET /v1/leaderboard/totals](https://docs.noether.exchange/developers/reference/leaderboard/get-leaderboard-totals)
    - API keys
      - [GET /v1/keys/beta-status](https://docs.noether.exchange/developers/reference/keys/get-keys-beta-status)
      - [POST /v1/keys/challenge](https://docs.noether.exchange/developers/reference/keys/post-keys-challenge)
      - [GET /v1/keys](https://docs.noether.exchange/developers/reference/keys/get-keys)
      - [POST /v1/keys](https://docs.noether.exchange/developers/reference/keys/post-keys)
      - [DELETE /v1/keys/{keyId}](https://docs.noether.exchange/developers/reference/keys/delete-keys-by-keyId)
    - Events and health
      - [GET /v1/health](https://docs.noether.exchange/developers/reference/system/get-health)
      - [GET /v1/events](https://docs.noether.exchange/developers/reference/system/get-events)
  - [WebSocket API](https://docs.noether.exchange/developers/websocket): Frames, the four channel families, connection limits and reconnect rules for the gateway's single WebSocket endpoint at /v1/ws.
  - [TypeScript SDK](https://docs.noether.exchange/developers/sdk-ts): Install noether-sdk 0.2.0 from npm, create a client, read markets, mint a key, trade with prepare, sign and submit, and stream channels.
  - [Python SDK](https://docs.noether.exchange/developers/sdk-py): Install noether-sdk 0.2.0 from PyPI, create the async client, read markets, issue a key, trade, and stream WebSocket channels.
  - [Errors](https://docs.noether.exchange/developers/errors): Gateway HTTP error bodies, how failed transactions surface contract and host errors, and the error code tables of the deployed contracts.

  - **Packages**
  - [noether-sdk on npm](https://www.npmjs.com/package/noether-sdk)
  - [noether-sdk on PyPI](https://pypi.org/project/noether-sdk/)
- Protocol: Contracts, oracle, mechanics, security
  - [Overview](https://docs.noether.exchange/protocol): Where to start for the contracts, the price chain, the trading maths, the network facts and the disclosure policy behind the Noether testnet.
  - [Architecture](https://docs.noether.exchange/protocol/architecture): A map of the six Noether contracts, the Noeracle price source and the off-chain services, and how one trade moves through them.
  - [Oracle and price feeds](https://docs.noether.exchange/protocol/oracle): How Noeracle attestations reach the chain, how the market reads them through the SEP-40 shim, and the checks that gate a trade.
  - [Trading mechanics](https://docs.noether.exchange/protocol/trading-mechanics): Precision, the margin ladder, per-market funding, liquidation, fee tiers and pool capacity limits as the deployed market and vault compute them.
  - [Contracts and events](https://docs.noether.exchange/protocol/contracts): Addresses for the testnet deployment and the guarded mainnet deployment, how to verify what the gateway serves, and every event the contracts emit.
  - [Networks](https://docs.noether.exchange/protocol/networks): Testnet and mainnet endpoints and passphrases, how the faucet hands out test USDC, what a testnet reset does to addresses, and what the guarded mainnet deployment means.
  - [Security and audits](https://docs.noether.exchange/protocol/security): Audit status, how to report a vulnerability, what is in and out of scope, and the interim reward policy from the repository's SECURITY.md.
  - [Changelog](https://docs.noether.exchange/protocol/changelog): User-facing changes to the app, the gateway API, the SDKs and the deployed contracts, newest first, with the dates that can be verified.