Authentication

All API requests require a Bearer token in the Authorization header. The same API key works for both REST API and MCP endpoints.

Terminal

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

Creating API Keys

Log in to your GoldenClaw Dashboard
Navigate to API Keys
Click Create New Key
Select the required scopes
Copy and securely store your key

One-time visibility

API keys are displayed only once at creation. If you lose a key, revoke it and create a new one.

Scopes

GoldenClaw uses granular scopes to control API access. Write scopes automatically include read access for the same resource.

Scope	Description	Free	Plus/Pro
`market:read`	Prices, OHLCV, pairs, symbols, tickers, timeframes	✓	✓
`indicators:read`	Technical indicator calculations	✓	✓
`account:read`	Account balance and information	✓	✓
`trade:spot:read`	View spot orders	✓	✓
`trade:spot:write`	Place/cancel spot orders	—	✓
`trade:futures:read`	View USD-M futures orders and positions	✓	✓
`trade:futures:write`	Place/cancel USD-M futures orders	—	✓
`trade:coinm-futures:read`	View COIN-M futures orders and positions	✓	✓
`trade:coinm-futures:write`	Place/cancel COIN-M futures orders	—	✓

Scope Selection Guide

Choose scopes based on your use case:

Use Case	Scopes
Market data + indicators	`market:read`, `indicators:read`
Read-only portfolio monitoring	+ `account:read`, `trade:futures:read`
Futures trading	+ `trade:futures:write`
Full access (all markets)	All 9 scopes

Good to know

Write scopes (trade:spot:write, trade:futures:write, trade:coinm-futures:write) require a Plus or Pro plan. Free tier includes 6 read-only scopes.

Plan Tiers

For plan limits, quotas, and feature comparison, see Pricing.

Rate Limit Headers

Every response includes rate limit information:

Response Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1741683600

The remaining field is also included in the response body under meta.remaining.

Error Responses

401 Unauthorized

Invalid or missing API key.

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" },
  "meta": { "timestamp": 1741683600000 }
}

403 Forbidden

API key lacks the required scope.

{
  "success": false,
  "error": { "code": "FORBIDDEN", "message": "Scope trade:futures:write required" },
  "meta": { "timestamp": 1741683600000 }
}

429 Rate Limited

Monthly request quota exceeded.

{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded" },
  "meta": { "timestamp": 1741683600000 }
}

Check X-RateLimit-Reset header for when your quota resets.

On this page