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

> [card] [@gainstrade/api](https://www.npmjs.com/package/@gainstrade/api)
>
> The package on npm, MIT licensed. Node 20 or newer, with `viem` 2 as a peer dependency.

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

```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`](https://api.gains.trade/openapi.json) (OpenAPI 3.1). Generate a client and add the signing helper from the [Authentication](https://docs.gains.trade/developer/trading-api/authentication.md#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](https://docs.gains.trade/developer/trading-api/hyperliquid-compatibility.md) 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.


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