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

# Trading API

> Trade on Gains from anywhere: a resource-oriented REST and WebSocket API, one signing scheme, your own keys, your own gas.

> [!NOTE]
>
> **The Trading API is in beta.** It is live on Arbitrum mainnet and the Arbitrum Sepolia testnet, and endpoints and fields are still being added. [Status](#status) lists what is not there yet.

The Trading API is the programmatic way to trade on Gains. It is the foundation for bots, terminals, copy-trading tools, the Claude MCP server and the TradingView broker integration. The API is non-custodial: you trade with an **agent key** the trader authorised on-chain once, Gains never holds funds or keys, and every transaction is prepared by the API but signed, paid for and broadcast by you. No gas is sponsored.

## SDK and OpenAPI spec

Install the TypeScript SDK from npm:

```bash theme={null}
npm install @gainstrade/api viem
```

> [card] [@gainstrade/api](https://www.npmjs.com/package/@gainstrade/api)
>
> The TypeScript SDK on npm. Node 20 or newer, with `viem` 2.

> [card] [gains-api-sdk](https://github.com/GainsNetwork-org/gains-api-sdk)
>
> The SDK source, its README and the issue tracker, on GitHub.

> [card] [openapi.json](https://api.gains.trade/openapi.json)
>
> The OpenAPI 3.1 spec, served by api.gains.trade. Generate a client in any language.

The spec to hand a generator is `https://api.gains.trade/openapi.json`, and the testnet deployment serves its own at `https://api-testnet.gains.trade/openapi.json`. The two differ only in the server URL.

## Two surfaces, one core

| Surface | Base path | Who it is for |
| - | - | - |
| **Native API** | `/v1/{chain}` | Anyone integrating Gains directly. Simple REST + JSON + WebSocket, one EIP-712 signing scheme, OpenAPI contract, generated SDKs. |
| **Hyperliquid facade** | `/hl/{chain}` | Anyone already integrated with Hyperliquid. Same request and response shapes, same signing; switch by changing the base URL. See [Hyperliquid compatibility](https://docs.gains.trade/developer/trading-api/hyperliquid-compatibility.md). |

Both surfaces share the agent model and the order lifecycle. Native agents broadcast their own transactions; the Hyperliquid facade relays them through a Gains relayer, the one place gas is sponsored, because Hyperliquid SDKs can only sign typed data. On mainnet that relayer is not enabled yet: the facade serves `POST /info` and the stream, and `POST /exchange` answers `CHAIN_READ_ONLY` until it is.

## Environments

| Environment | REST | WebSocket |
| - | - | - |
| Mainnet | `https://api.gains.trade/v1/{chain}` | `wss://api.gains.trade/v1/{chain}/ws` |
| Testnet | `https://api-testnet.gains.trade/v1/arbitrum-sepolia` | `wss://api-testnet.gains.trade/v1/arbitrum-sepolia/ws` |

`chain` is `arbitrum` on mainnet today (`base`, `polygon` and `megaeth` follow on the same paths) and `arbitrum-sepolia` on testnet. Every resource is scoped to one chain; positions on Base will not be visible through `/v1/arbitrum`. `GET /v1/{chain}` returns the chain id, the Diamond address and the signing domain.

## What "simple" means here

| On other venues | On Gains |
| - | - |
| One `POST /info` and one `POST /exchange` with a `type` discriminator | `GET /markets`, `POST /orders`, `GET /account/{address}/positions`: standard verbs, standard status codes |
| Custom hashing of msgpack payloads before signing | One EIP-712 struct per operation over the request itself. Any web3 library signs it with `signTypedData` |
| Per-asset decimal rules learned by trial and error | Precision published per market by `GET /markets`; out-of-precision values are rejected with a clear error, never rounded silently |
| Hand-written SDKs that drift from the server | The OpenAPI 3.1 document is generated from the server's own schemas and is the source the SDKs are built from |
| Several ids per order and several cancel flows | One `id` for the whole lifecycle, an optional `clientId` for idempotency, one `DELETE /orders/{id}` |

## Order lifecycle in one paragraph

Gains fills market orders through its oracle network rather than a matching engine. `POST /orders` answers `prepared` with the `id` you will keep for the rest of the lifecycle and the transaction to sign and broadcast; once it is mined (report the hash with `POST /orders/{id}/submit`, or let the chain watcher see it) the order is `pending`. Within seconds the status becomes `filled` (with price, size and fees), `rejected` (with the reason) or, if the oracle never answers, `timed_out`, in which case `DELETE /orders/{id}` prepares the reclaim of the collateral. Limit and stop orders rest as `open` until triggered or `canceled`. Track any order with `GET /orders/{id}`, the `orders` WebSocket channel, or `order.waitForFill()` in the SDK. Details in [Orders](https://docs.gains.trade/developer/trading-api/orders.md).

## Where to start

> [card] [Quickstart](https://docs.gains.trade/developer/trading-api/quickstart.md)
>
> Authorise an agent and fill a first test order on testnet in under 15 minutes.

> [card] [Authentication](https://docs.gains.trade/developer/trading-api/authentication.md)
>
> Agents, scopes, the EIP-712 request signature, read-only API keys.

> [card] [Orders and positions](https://docs.gains.trade/developer/trading-api/orders.md)
>
> Sizes, prices, leverage, the lifecycle and every error you can get.

> [card] [API reference](https://docs.gains.trade/api-reference/markets/list-markets.md)
>
> Every endpoint, generated from the OpenAPI contract.

> [card] [SDKs and examples](https://docs.gains.trade/developer/trading-api/sdks.md)
>
> The TypeScript SDK, generated clients, and five worked example projects.

## Status

The API is in beta, live on Arbitrum mainnet, with the Sepolia testnet for trying the flow without funds. Isolated margin only (`onlyIsolated: true` on every market); cross margin, TWAP and trailing stops follow their own tickets and will land as new fields on the same resources. Breaking changes ship under a new `/v2` prefix, never under `/v1`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.