Quickstart

You need a wallet with testnet USDC on Arbitrum Sepolia (the trader, called the master wallet), a little testnet ETH for the agent key (it pays the gas of its own transactions) and Node 20 or newer. Ask for testnet USDC in the Discord #testnet channel; the trading contracts on Sepolia are the same as mainnet.

Install the SDK

npm install @gainstrade/api viem

The SDK is generated from the API’s OpenAPI contract; every request and response is typed. If you prefer another language, skip to plain HTTP or generate a client from the spec (SDKs).

Create an agent key

The agent is a fresh EVM key that signs API requests and broadcasts the transactions the API prepares, so it needs a little ETH for gas. It never holds collateral. Keep it in an environment variable or a secret manager, never in source.

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";

const agentKey = generatePrivateKey();
console.log("GAINS_AGENT_KEY=" + agentKey);
const agent = privateKeyToAccount(agentKey);
console.log("agent address", agent.address);

Authorise the agent with the master wallet

Two things happen: the API records the agent and its scope (signed by the master wallet), and the master wallet sends one on-chain transaction, setTradingDelegate(agent), which names the agent as the trader’s delegate. The API returns that transaction ready to send. The client is built with a sender: the agent’s wallet client, which will sign and broadcast every prepared transaction.

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

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

const { agent: registered, delegationTx } = await client.agents.authorize(master, {
  agent: agent.address,
  name: "quickstart-bot",
  scope: {
    markets: ["BTC/USD", "ETH/USD"],
    maxLeverage: "20",
    dailySpendCapUsd: "1000",
    expiresAt: Date.now() + 30 * 24 * 3600 * 1000,
    permissions: "trade",
  },
});
console.log(registered.status); // "pending_delegation"

if (delegationTx !== null) {
  const wallet = createWalletClient({ account: master, chain: arbitrumSepolia, transport: http() });
  const hash = await wallet.sendTransaction({ to: delegationTx.to, data: delegationTx.data });
  console.log("delegation tx", hash);
}

Once the transaction is mined, client.agents.get(agent.address) reports status: "active". The delegation is per trader and per chain, and removeTradingDelegate cuts it. A trader who wants to sign with its own wallet registers itself as agent: no delegation, delegationTx is null.

Approve USDC once

The trader’s collateral stays in the trader’s wallet. The Diamond pulls it when an order opens, so the master wallet must approve the Diamond for USDC once (any amount, maxUint256 is common). GET /v1/{chain} returns the Diamond address (diamond) and GET /v1/{chain}/markets the USDC token address (collaterals[].address); both are also in the contracts reference.

Place a market order and wait for the fill

const btc = await client.markets.get("BTC/USD");
console.log(btc.pricePrecision, btc.sizePrecision, btc.minPositionUsd);

const order = await client.orders.create({
  market: "BTC/USD",
  side: "long",
  type: "market",
  size: "0.001",
  leverage: "10",
  collateral: "USDC",
  slippage: "1",
  reduceOnly: false,
  clientId: crypto.randomUUID(),
});
console.log(order.id, order.status); // "5316911983139663" "pending"

const filled = await order.waitForFill({ timeoutMs: 90_000 });
console.log(filled.fill?.price, filled.fill?.size, filled.fill?.positionId);

size is in base asset (here BTC). The API derives the USDC collateral from size × price / leverage, simulates the order from the agent and returns the transaction; orders.create signs and broadcasts it with the sender, reports the hash (POST /orders/{id}/submit) and returns the pending order. waitForFill polls GET /orders/{id} and throws OrderNotFilledError on rejected, timed_out, canceled or expired, so an unfilled order never looks like a filled one.

Read the position, then close it

const positions = await client.account.positions(master.address);
const position = positions.find((p) => p.market === "BTC/USD")!;
console.log(position.unrealizedPnl, position.liquidationPrice);

const close = await client.positions.close(position.id, { slippage: "1" });
await close.waitForFill();

The same flow in plain HTTP

Every private request carries four headers. The signature is EIP-712 over the request itself; see Authentication for the exact struct.

X-Gains-Agent:     0xAgentAddress
X-Gains-Timestamp: 1700000000000        (ms, within 30 s of server time)
X-Gains-Nonce:     1700000000000001     (unique per agent inside the replay window)
X-Gains-Signature: 0x...                (65-byte EIP-712 signature)

# signing domain of the chain (chain id, Diamond, field list)
curl https://api-testnet.gains.trade/v1/arbitrum-sepolia

# public: no headers
curl https://api-testnet.gains.trade/v1/arbitrum-sepolia/markets/BTC-USD

# private write
curl -X POST https://api-testnet.gains.trade/v1/arbitrum-sepolia/orders \
  -H 'content-type: application/json' \
  -H 'X-Gains-Agent: 0x...' -H 'X-Gains-Timestamp: ...' -H 'X-Gains-Nonce: ...' -H 'X-Gains-Signature: 0x...' \
  -d '{"market":"BTC/USD","side":"long","type":"market","size":"0.001","leverage":"10","collateral":"USDC","slippage":"1","reduceOnly":false}'

Market symbols in paths are written BTC-USD (or URL-encoded BTC%2FUSD); in JSON bodies they are BTC/USD. The write above answers 201 with { order, transaction }. Sign and broadcast transaction with the agent key (eth_sendTransaction with to, data, value: "0"), then report the hash:

curl -X POST https://api-testnet.gains.trade/v1/arbitrum-sepolia/orders/5316911983139663/submit \
  -H 'content-type: application/json' -H 'X-Gains-Agent: 0x...' -H 'X-Gains-Timestamp: ...' -H 'X-Gains-Nonce: ...' -H 'X-Gains-Signature: 0x...' \
  -d '{"txHash":"0x..."}'

Authentication: scopes, revocation, read-only keys, the signature spec.
Orders and positions: limit and stop orders, partial closes, SL/TP, leverage changes.
WebSocket: stream prices, the book and your order updates instead of polling.

Trading API

API Reference

Integrators

Technical Reference

The same flow in plain HTTP

Next

​The same flow in plain HTTP

​Next

The same flow in plain HTTP

Next