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

# SDKs

> The OpenAPI document is the contract. TypeScript ships first; every other language is generated from the same file.

## TypeScript: `@gainstrade/api`

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

```ts theme={null}
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](/developer/trading-api/authentication#signing-a-request) 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](/developer/trading-api/hyperliquid-compatibility) 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.