---
name: trading
description: Execute trading operations on TTC Box across 29 exchanges. Place orders, manage positions, set leverage, and control risk. Use when you need to execute trades, modify positions, or manage exchange accounts.
license: Proprietary
compatibility: Designed for Claude Code (or similar products)
metadata:
  author: ttcbox
  version: "1.0"
  category: "trading"
  emoji: "📈"
---

## Skill Files

| File                     | URL                                          |
| ------------------------ | -------------------------------------------- |
| **SKILL.md** (this file) | `https://tetrac.xyz/skills/trading/SKILL.md` |

## Overview

This skill provides trading operations:

1. **Orders** - Place, cancel, and manage orders
2. **Positions** - View and close positions
3. **Account** - Set leverage, hedge mode, get balance
4. **Risk** - Stop losses, take profits

---

## Prerequisites

### 1. Authentication — TTC Auth Token

All requests require a TTC auth token obtained from the login endpoint:

```bash
curl -X POST https://tetrac.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "passKey": "YOUR_PASSKEY" }'
```

The response returns an `authToken` — pass it as the `ttc-auth-token` header on every request, along with your wallet public key:

| Header           | Description                                     |
| ---------------- | ----------------------------------------------- |
| `ttc-auth-token` | The `authToken` returned from `/api/auth/login` |
| `ttc-public-key` | Your wallet public key                          |

### 2. Exchange Credentials

Each request also includes your exchange-specific credentials in the body:

```json
{
  "credentials": {
    "apiKey": "YOUR_EXCHANGE_API_KEY",
    "apiSecret": "YOUR_EXCHANGE_API_SECRET",
    "passphrase": "YOUR_API_PASSPHRASE"
  }
}
```

| Field           | Required                   | Description                                                                   |
| --------------- | -------------------------- | ----------------------------------------------------------------------------- |
| `apiKey`        | Yes                        | Your exchange API key                                                         |
| `apiSecret`     | Yes                        | Your exchange API secret                                                      |
| `passphrase`    | For some exchanges         | API passphrase (required by Orderly, OKX, KuCoin, Bitget, BloFin, GRVT)       |
| `walletAddress` | Orderly (email users only) | Your main Solana wallet address for Orderly account ID derivation (see below) |

> **Note:** `getTickers` is a public method and does not require credentials.

### Orderly Network — Agentic / CLI Users

Orderly derives your account ID from your **main wallet address** + broker ID. If you registered via **email** (the agentic path), your `ttc-public-key` is a random DB identifier — not your Orderly trading wallet. You must pass `walletAddress` in credentials so the server can derive the correct account ID:

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "orderly",
    "method": "getPositions",
    "params": {},
    "credentials": {
      "apiKey": "YOUR_ORDERLY_ED25519_PUBLIC_KEY",
      "apiSecret": "YOUR_ORDERLY_ED25519_PRIVATE_KEY",
      "passphrase": "ttc",
      "walletAddress": "YOUR_SOLANA_MAIN_WALLET_ADDRESS"
    }
  }'
```

**Web3 users** can omit `walletAddress` — the server automatically uses `ttc-public-key` (which IS their main wallet).

---

## Place Orders

### Limit Order

Place a buy limit order at a specific price:

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "phemex",
    "method": "placeLimitOrder",
    "params": {
      "symbol": "BTCUSDT",
      "side": "buy",
      "quantity": 0.001,
      "price": 95000,
      "positionSide": "long",
      "timeInForce": "GoodTillCancel"
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET",
      "passphrase": "YOUR_API_PASSPHRASE"
    }
  }'
```

> Omit `passphrase` if the exchange does not require one.

### Market Order

Execute immediately at current price:

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "bybit",
    "method": "placeMarketOrder",
    "params": {
      "symbol": "ETHUSDT",
      "side": "sell",
      "quantity": 0.1,
      "positionSide": "short"
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Stop Loss Order

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "binance",
    "method": "placeStopOrder",
    "params": {
      "symbol": "BTCUSDT",
      "side": "sell",
      "quantity": 0.001,
      "stopPrice": 90000,
      "positionSide": "long",
      "triggerType": "ByMarkPrice"
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Order Response

```json
{
  "success": true,
  "data": {
    "orderId": "1234567890",
    "symbol": "BTCUSDT",
    "side": "buy",
    "positionSide": "long",
    "type": "limit",
    "price": 95000,
    "quantity": 0.001,
    "status": "new",
    "timestamp": 1738435234567
  },
  "code": 200,
  "exchange": "phemex"
}
```

---

## Manage Positions

### Get Positions

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "phemex",
    "method": "getPositions",
    "params": {},
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Positions Response

```json
{
  "success": true,
  "data": [
    {
      "symbol": "BTCUSDT",
      "side": "buy",
      "positionSide": "long",
      "size": 0.001,
      "entryPrice": 95000,
      "markPrice": 97500,
      "pnl": 2.5,
      "leverage": 10,
      "liquidationPrice": 86500,
      "marginType": "cross",
      "unrealizedPnl": 25.0,
      "notional": 95.0
    }
  ],
  "code": 200,
  "exchange": "phemex"
}
```

### Close All Positions

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "phemex",
    "method": "closeAllPositions",
    "params": {},
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

---

## Account Management

### Set Leverage

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "binance",
    "method": "setLeverage",
    "params": {
      "symbol": "BTCUSDT",
      "leverage": 10
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Set Hedge Mode

Enable long and short positions simultaneously:

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "bybit",
    "method": "setHedgeMode",
    "params": {
      "symbol": "BTCUSDT",
      "isHedged": true
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Get Balance

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "binance",
    "method": "getBalance",
    "params": {},
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Balance Response

```json
{
  "success": true,
  "data": [
    {
      "asset": "USDT",
      "balance": "1000.00",
      "available": "950.00",
      "locked": "50.00"
    },
    {
      "asset": "BTC",
      "balance": "0.05",
      "available": "0.05",
      "locked": "0"
    }
  ],
  "code": 200,
  "exchange": "binance"
}
```

---

## Order Management

### Get Open Orders

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "binance",
    "method": "getOrders",
    "params": {},
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Cancel All Orders

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "binance",
    "method": "cancelAllOrders",
    "params": {
      "symbol": "BTCUSDT"
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

### Cancel Specific Order

```bash
curl -X POST https://tetrac.xyz/api/v1/exchanges \
  -H "ttc-auth-token: YOUR_AUTH_TOKEN" \
  -H "ttc-public-key: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeName": "bybit",
    "method": "cancelOrder",
    "params": {
      "symbol": "BTCUSDT",
      "orderID": "1234567890"
    },
    "credentials": {
      "apiKey": "YOUR_EXCHANGE_API_KEY",
      "apiSecret": "YOUR_EXCHANGE_API_SECRET"
    }
  }'
```

---

## Order Parameters Reference

| Parameter         | Type    | Required  | Description                                                     |
| ----------------- | ------- | --------- | --------------------------------------------------------------- |
| `symbol`          | string  | Yes       | Trading pair (e.g., `BTCUSDT`)                                  |
| `side`            | string  | Yes       | `buy` or `sell`                                                 |
| `quantity`        | number  | Yes       | Order quantity                                                  |
| `price`           | number  | For limit | Limit price                                                     |
| `stopPrice`       | number  | For stop  | Stop trigger price                                              |
| `positionSide`    | string  | No        | `long`, `short`, or `merged` (hedge mode)                       |
| `orderType`       | string  | No        | `market`, `limit`, `stop`, `stoplimit`                          |
| `timeInForce`     | string  | No        | `GoodTillCancel`, `ImmediateOrCancel`, `FillOrKill`, `PostOnly` |
| `reduceOnly`      | boolean | No        | Only reduce existing position                                   |
| `closePosition`   | boolean | No        | Close entire position                                           |
| `triggerType`     | string  | No        | `ByLastPrice`, `ByMarkPrice`, `ByIndexPrice`                    |
| `takeProfitPrice` | number  | No        | Take profit price                                               |
| `stopLossPrice`   | number  | No        | Stop loss price                                                 |

---

## Available Methods

| Method                | Description                              |
| --------------------- | ---------------------------------------- |
| `setHedgeMode`        | Set hedge mode for the exchange account  |
| `setLeverage`         | Set leverage for a specific trading pair |
| `getPositions`        | Retrieve current open positions          |
| `getBalance`          | Get account balance information          |
| `placeLimitOrder`     | Execute a limit order                    |
| `placeMarketOrder`    | Execute a market order                   |
| `placeStopOrder`      | Place a stop order                       |
| `closeAllPositions`   | Close all open positions                 |
| `getOrders`           | Retrieve open or historical orders       |
| `cancelAllOrders`     | Cancel all open orders                   |
| `cancelOrder`         | Cancel a specific order by ID            |
| `getTickers`          | Get current ticker information           |
| `getBestBidAsk`       | Get best bid and ask prices              |
| `getUserTradeHistory` | Retrieve user's historical trade records |
| `getDepositAddress`   | Get deposit address for a specific asset |
| `createWithdrawal`    | Initiate a withdrawal from the exchange  |

---

## Supported Exchanges

**29 Supported Exchanges:**

CEX Perps

- Aevo
- AscendEX
- Binance
- BingX
- Bitget
- BitMEX
- BloFin
- Bybit
- KuCoin
- MEXC
- OKX
- Phemex
- Woox

DEX Perps

- Apex
- AsterDex
- dYdX
- Flash
- GRVT
- Hyperliquid
- Lighter
- Orderly Network
- Pacifica
- Paradex
- Propr
- Reya
- Variational
- Vest

> Extended exchange support is also available via the `extended` adapter.

---

## Rate Limits

| Action             | Default | High Karma (1000+) |
| ------------------ | ------- | ------------------ |
| Trading Operations | 30/min  | 100/min            |

---

## Best Practices

1. **Test with small amounts first** - Verify your integration works
2. **Use reduceOnly for exits** - Prevents accidental position opens
3. **Set stop losses** - Always manage risk
4. **Monitor rate limits** - Avoid being blocked
5. **Secure credentials** - Never share API keys

---

## Next Steps

- Explore [market data](https://tetrac.xyz/skills/market-data/SKILL.md)
- Explore [x402 agent payments](https://tetrac.xyz/skills/x402-agent-payments/SKILL.md)

---

**Full API Documentation:** https://tetrac.xyz/docs/api