Best Practices

Rate Limit Management

GoldenClaw enforces monthly request quotas per plan. Avoid hitting limits with these strategies:

Check remaining quota — Every response includes meta.remaining and X-RateLimit-Remaining header. Monitor these values before batch operations.

Cache static data — Exchange lists, trading pairs, symbols, and timeframes rarely change. Cache them locally and refresh daily instead of per-request.

Handle 429 responses — When rate-limited, implement exponential backoff. Check X-RateLimit-Reset for the exact reset timestamp.

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

Batch indicator calculations — Use POST /indicators/{category} with complete OHLCV data instead of making multiple calls. One request can calculate any indicator within a category.

API Key Security

Never expose keys client-side — API keys grant access to trading operations. Never include them in frontend code, browser requests, or public repositories.

Use environment variables — Store keys in .env files or secret managers. Reference them in your application code:

GOLDENCLAW_API_KEY=gc_live_abc123...

Separate keys per environment — Create distinct keys for development, staging, and production. Revoke unused keys promptly.

Use minimum scopes — If your integration only reads market data, don't add trading scopes. Fewer scopes = smaller blast radius if a key is compromised.

Rotate keys periodically — Create a new key, update your integration, verify it works, then revoke the old key.

Exchange Selection

Not all exchanges support all market types or features.

Check capabilities first — Call GET /exchanges to see what each exchange supports:

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

Broadest support — Binance, Bybit, and OKX support spot, futures, and COIN-M futures with the most complete feature set.

Market type matters — A symbol like BTC/USDT exists on different market types with different trading rules. Always specify marketType explicitly.

Technical Indicators

Choose the right timeframe — Indicators calculated on 1-minute candles produce noisy signals. Use 1h or 4h for swing trading, 1d for position trading.

Provide sufficient data — Most indicators need a warm-up period. Request at least 2x the indicator period in OHLCV data. For a 14-period RSI, fetch at least 30 candles.

Combine indicators — No single indicator is reliable alone. Combine trend (MACD, EMA) with momentum (RSI) and volatility (Bollinger Bands) for confirmation.

Available categories:

Error Handling

Always check success — Don't assume a 200 status means everything worked. Parse the success field in the response body.

const response = await fetch(url, { headers });
const data = await response.json();

if (!data.success) {
  console.error(`${data.error.code}: ${data.error.message}`);
  return;
}

// Use data.data safely

Retry on 5xx errors — Server errors are transient. Retry with exponential backoff (1s, 2s, 4s). Don't retry 4xx errors — they indicate a client-side issue.

Handle exchange-specific errors — Exchanges may be under maintenance, symbols may be delisted, or markets may be closed. The error message will include context about the underlying exchange issue.

Log correlation data — Include the meta.timestamp from error responses when filing support requests. It helps us trace your specific request.