> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noise.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Trader API

> Programmatic trading on Noise with a self-custodied wallet.

The Trader API is the programmatic interface to the Noise Exchange, for market makers, bots, and anyone who would rather trade from code than from the app.

It is a **self-custody** API. Every order is signed by the wallet that holds the funds, and Noise holds no key capable of trading on a trader's behalf. A Noise API credential identifies a wallet and rate-limits it; on its own it cannot open a position or move money.

## Requirements

<Steps>
  <Step title="A self-held signing key">
    An EOA on Base whose private key is available to the client for signing. See [Choosing a wallet](/trader-api/authentication#choosing-a-wallet), which covers exporting the key for a Noise app wallet.
  </Step>

  <Step title="An API credential">
    Sign a one-off attestation with that wallet to mint an API key and secret. See [Authentication](/trader-api/authentication).
  </Step>

  <Step title="An exchange account with funds">
    Register the wallet, approve collateral, and fund it. See [Getting Tradeable](/trader-api/getting-tradeable).
  </Step>
</Steps>

From there, the remaining guides cover [orders](/trader-api/orders) and [streams](/trader-api/streams).

## Base URL and environments

Every route is under the base path `/api/trader/v1`, and the WebSocket is at `/ws`. Hostnames are published with each deployment.

The **development deployment is the sandbox**: it issues real API credentials against test funds, which allows an integration to be exercised end to end before capital is at risk. Start there.

The sandbox runs against a testnet, so its `chainId` and contract addresses differ from production. Take both from `GET /status` on the deployment being targeted; the chain IDs in the examples below are illustrative.

Each deployment also serves its own live reference. Both sit at the host root, outside the `/api/trader/v1` prefix:

| Path            | What it is                    |
| --------------- | ----------------------------- |
| `/docs`         | Interactive API explorer      |
| `/openapi.json` | The raw OpenAPI specification |

Those are generated from the same specification that serves the API, so where these guides and the explorer ever disagree, the explorer is right.

## Read the deployment before signing

`GET /status` publishes the chain IDs and contract addresses that signatures commit to, plus the live rate-limit table.

Read it at startup rather than hardcoding the values. A signature built against a stale clearing-house address is rejected, and the collateral token is not always canonical Circle USDC.

```bash theme={null}
curl https://<host>/api/trader/v1/status
```

```json theme={null}
{
  "status": "active",
  "serverTime": 1757260800000,
  "exchange": {
    "chainId": 8453,
    "attestationChainId": 8453,
    "clearingHouseAddress": "0x...",
    "collateralTokenAddress": "0x...",
    "collateralCurrency": "USDC"
  },
  "rateLimits": [{ "useCase": "trader_order_submit", "limit": 100, "windowSeconds": 10 }]
}
```

All market data and status routes are public. Everything else needs a credential, except key minting and rotation, which are authorized by the wallet signature itself.

## Conventions

* **All monetary and quantity values are decimal strings**, in both requests and responses, never JSON numbers. Parse them with a decimal library, not floating-point arithmetic.
* **`GET /account/orders` and `GET /account/trades` use cursor pagination.** Pass `before=<cursor>` and read `nextCursor`, which is `null` on the last page. There are no offsets: new fills insert at the head, so an offset would skip or repeat rows. Other list routes return a single unpaginated response and carry no `nextCursor`.
* **Timestamp units vary by field, so check the field rather than assuming one convention.** In **Unix seconds**: `x-noise-timestamp`, the attestation `timestamp`, an order's `expiry` (in both directions, matching what was signed), and the `x-ratelimit-reset` header. In **epoch milliseconds**: `serverTime` on `GET /status` and on `system:heartbeat`, and price-point timestamps. Do not compare across the two without converting.
* The API uses the internal names for the two prices: `midPrice` is what the app calls **market price**, and `markPrice` is what it calls **relevance**. See [How It Works](/how-it-works).

## Endpoints at a glance

All paths are relative to `/api/trader/v1`. **Public** routes need no credential, **Attestation** routes are authorized by a wallet signature instead of a key, and **Key** routes need [signed request headers](/trader-api/authentication#signing-requests).

| Route                             | Access      | Purpose                                                         |
| --------------------------------- | ----------- | --------------------------------------------------------------- |
| `GET /status`                     | Public      | Chain IDs, contract addresses, rate limits, trading status      |
| `GET /assets`                     | Public      | Markets, `marketId`, tick and lot size, ticker state            |
| `GET /assets/{id}/stats`          | Public      | Market price, relevance, volume, open interest, funding         |
| `GET /assets/{id}/prices`         | Public      | Price history over a window                                     |
| `GET /assets/{id}/auction`        | Public      | Opening-auction phase for a market, and whether it takes orders |
| `POST /keys`                      | Attestation | Mint a credential from an attestation                           |
| `POST /keys/rotate`               | Attestation | Rotate at nonce + 1                                             |
| `GET /keys`                       | Key         | List issued keys (metadata only)                                |
| `DELETE /keys/{apiKey}`           | Key         | Revoke a key                                                    |
| `POST /account/register`          | Key         | Give the wallet an exchange account                             |
| `GET /account/approval`           | Key         | Unsigned collateral approval for the wallet to broadcast        |
| `GET /account/balance`            | Key         | Registration state and capital                                  |
| `GET /account/positions`          | Key         | Open positions and their risk fields                            |
| `GET /account/orders`             | Key         | Orders, paginated; `open=true` restricts to open orders         |
| `GET /account/orders/{orderHash}` | Key         | One order, including `rejectCode`                               |
| `GET /account/trades`             | Key         | Fills, paginated                                                |
| `GET /account/funding`            | Key         | Cumulative funding on open positions                            |
| `POST /orders`                    | Key         | Submit a signed order                                           |
| `POST /orders/batch`              | Key         | Up to 20 orders                                                 |
| `POST /orders/{orderHash}/cancel` | Key         | Cancel one                                                      |
| `POST /orders/batch-cancel`       | Key         | Up to 50 cancels                                                |
| `POST /orders/cancel-all`         | Key         | Cancel everything                                               |
| `POST /orders/cancel-all-after`   | Key         | Dead man's switch                                               |
| `GET /health`                     | Public      | Liveness                                                        |

## Terms

<Info>
  These guides describe the API contract. Nothing here is trading, investment, or tax advice, and
  running a bot against a live market risks real capital.
</Info>