API Guide

Base URL

https://stage.goldenclaw.sh/api/v1

Authentication

Include your API key as a Bearer token:

Terminal

curl "https://stage.goldenclaw.sh/api/v1/..." \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for scopes and plan details.

Common Parameters

Most endpoints require these parameters:

Parameter	Type	Required	Description
`exchange`	string	✓	Exchange ID: `binance`, `bybit`, `okx`, `kucoin`, `gate`, `htx`, `bitget`, `bingx`, `bitmart`, `bitmex`, `coinex`, `hyperliquid`
`marketType`	string	✓	Market: `spot`, `futures`, `coinm-futures`
`symbol`	string	Most	Trading pair, e.g. `BTC/USDT`, `ETH/USDT`

Good to know

Use GET /exchanges to check which exchanges support which market types and features.

Request Format

GET endpoints accept query parameters
POST endpoints accept JSON body with Content-Type: application/json

GET example

curl "https://stage.goldenclaw.sh/api/v1/market/price?exchange=binance&marketType=futures&symbol=BTC/USDT" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST example

curl -X POST "https://stage.goldenclaw.sh/api/v1/trading/orders/place" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "binance",
    "marketType": "futures",
    "symbol": "BTC/USDT",
    "side": "BUY",
    "type": "MARKET",
    "quantity": 0.001,
    "leverage": 10
  }'

Response Format

Success

{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "price": 87432.50
  },
  "meta": {
    "timestamp": 1741683600000,
    "remaining": 9847
  }
}

Field	Type	Description
`success`	boolean	Always `true` for successful responses
`data`	object	Response payload (varies by endpoint)
`meta.timestamp`	number	Server timestamp (Unix ms)
`meta.remaining`	number	Remaining requests in current period

Error

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid symbol: INVALID"
  },
  "meta": {
    "timestamp": 1741683600000
  }
}

Error Codes

HTTP	Code	Description
400	`BAD_REQUEST`	Invalid parameters or request body
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	API key lacks required scope
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMITED`	Monthly request quota exceeded
500	`INTERNAL_ERROR`	Server error (details hidden in production)

Endpoints

Exchange

Method	Path	Scope	Description
GET	`/exchanges`	`market:read`	List supported exchanges with capabilities

Market Data

Method	Path	Scope	Description
GET	`/market/price`	`market:read`	Current price for a symbol
GET	`/market/ohlcv`	`market:read`	OHLCV candlestick data
GET	`/market/pairs`	`market:read`	Available trading pairs
GET	`/market/symbols`	`market:read`	Symbol details for an exchange
GET	`/market/ticker`	`market:read`	24h ticker statistics
GET	`/market/timeframes`	`market:read`	Supported timeframes

Trading

Method	Path	Scope	Description
POST	`/trading/orders/place`	`trade:*:write`	Place an order (MARKET, LIMIT, STOP, STOP_LIMIT)
POST	`/trading/orders/cancel`	`trade:*:write`	Cancel an open order
GET	`/trading/orders`	`trade:*:read`	List open orders for a symbol
GET	`/trading/positions`	`trade:*:read`	List open positions
POST	`/trading/positions/close`	`trade:*:write`	Close an open position

Account

Method	Path	Scope	Description
GET	`/account/balance`	`account:read`	Account balance with multi-currency breakdown
GET	`/account/info`	`account:read`	Full account information

Indicators

Method	Path	Scope	Description
GET	`/indicators/{category}`	`indicators:read`	List available indicators in a category
POST	`/indicators/{category}`	`indicators:read`	Calculate a technical indicator

Categories: trend, momentum, volatility, volume, support-resistance

MCP Alternative

All the same functionality is available via Model Context Protocol at:

POST https://stage.goldenclaw.sh/mcp

MCP uses the same API key (Bearer token) and counts toward the same rate limits. See MCP Tools for the full tool catalog.

On this page