SDKs

TypeScript: `@gainstrade/api`

npm install @gainstrade/api viem

import { GainsClient, viemSender } from "@gainstrade/api";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { arbitrum } from "viem/chains";

const agent = privateKeyToAccount(process.env.GAINS_AGENT_KEY as `0x${string}`);
const client = new GainsClient({
  chain: "arbitrum",
  agent,
  sender: viemSender(createWalletClient({ account: agent, chain: arbitrum, transport: http() })),
});

const order = await client.orders.create({ market: "ETH/USD", side: "short", type: "limit", price: "3500", size: "1", leverage: "5", collateral: "USDC", slippage: "1", reduceOnly: false });
console.log(order.id, order.status); // "..." "open"

Piece	What it gives you
`client.markets`, `client.account`, `client.orders`, `client.positions`, `client.agents`	One method per endpoint, typed from the OpenAPI document.
`AgentSigner`	The EIP-712 request signature; nonces handled. Implement `RequestSigner` to sign elsewhere (KMS, hardware).
`TransactionSender`, `viemSender(walletClient)`	Signs and broadcasts the prepared transactions with the agent key. Implement the interface for a custom signer; without a sender the writes throw `NO_SENDER` and `orders.prepare()` / `submit()` remain available.
`TrackedOrder.waitForFill()`, `waitFor([...statuses])`	Polls `GET /orders/{id}`; resolves on `filled` (or the given statuses), throws `OrderNotFilledError` or `FillTimeoutError`.
`orders.create` / `cancel` / `update`, `positions.close` / `update`	Prepare, sign, broadcast and submit in one call; `cancel` and `update` return `{ txHash, result }`.
`client.account.allFills()`	Async iterator that follows cursors.
`client.websocket()`	Reconnecting WebSocket with `on(channel, ...)` and `for await (const m of ws.messages("orders"))`.
`GainsApiError`	`code`, `status`, `details`, `retryable`.
`apiKey` option	Private reads without a signer.

Node 20 needs a WebSocket implementation passed to client.websocket({ WebSocket }) (the ws package); Node 22+ and browsers use the built-in one. A client signs for the public Diamond of its chain. Pointed at another deployment through baseUrl (staging, a preview environment, a self-hosted API), pass that deployment’s domain as signingChain: { chainId, diamond }, the values GET /v1/{chain} reports there; without it, a deployment whose Diamond differs is refused with SIGNING_CHAIN_MISMATCH before any request is signed. client.signingChain() returns the domain in use. Worked examples live in the monorepo under miniapps/trading-api-examples: a first trade end to end, a resting-order market maker on the WebSocket, a TradingView webhook receiver, a public-data tape, and the Hyperliquid Python SDK against the facade.

Other languages

The contract is https://api.gains.trade/openapi.json (OpenAPI 3.1). Generate a client and add the signing helper from the Authentication page, which is under forty lines with any EIP-712 library.

Language	Generator	Signing
Python	`openapi-python-client`	`eth_account.messages.encode_typed_data`
Go	`ogen` or `oapi-codegen`	`go-ethereum` `apitypes.TypedData`
Rust	`openapi-generator` (3.1 support is partial: flatten `anyOf` nulls first)	`alloy` `sol!` typed data

A published gains-api package on PyPI follows the mainnet release; until then generate from the spec.

CCXT

A CCXT adapter (gains) is planned on top of this API so bots and MCP servers that already speak CCXT get Gains without custom code. Track it on the changelog.

Hyperliquid SDKs

If you already use the official Hyperliquid Python SDK or @nktkas/hyperliquid, point them at https://api.gains.trade/hl/{chain} and read the compatibility page for what changes. The Python SDK’s Info client (meta, l2Book, allMids, clearinghouseState, openOrders) is verified against the facade as is; an SDK given a custom base URL signs L1 actions as testnet, and the facade accepts both phantom-agent sources.

Trading API

API Reference

Integrators

Technical Reference

TypeScript: `@gainstrade/api`

Other languages

CCXT

Hyperliquid SDKs

​TypeScript: @gainstrade/api

​Other languages

​CCXT

​Hyperliquid SDKs

TypeScript: `@gainstrade/api`

Other languages

CCXT

Hyperliquid SDKs