Skip to main content
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 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:

@gainstrade/api

The TypeScript SDK on npm. Node 20 or newer, with viem 2.

gains-api-sdk

The SDK source, its README and the issue tracker, on GitHub.

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

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

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

​
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.

​
Where to start

Quickstart

Authorise an agent and fill a first test order on testnet in under 15 minutes.

Authentication

Agents, scopes, the EIP-712 request signature, read-only API keys.

Orders and positions

Sizes, prices, leverage, the lifecycle and every error you can get.

API reference

Every endpoint, generated from the OpenAPI contract.

SDKs and examples

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.