Troubleshooting

Quick Checklist

Before diving into specific issues, check:

1. API key is valid and not revoked
2. API key has the required scopes for your operation
3. URL is https://stage.goldenclaw.sh/api/v1 (REST) or https://stage.goldenclaw.sh/mcp (MCP)
4. exchange and marketType parameters are included
5. Exchange credentials are configured in your Dashboard

Authentication Issues

401 Unauthorized

Invalid or missing API key.

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

Check: Is the key copy-pasted correctly? No trailing spaces? Key not revoked?

403 Forbidden — Insufficient scope

Your API key doesn't have the required scope.

{ "error": { "code": "FORBIDDEN", "message": "Scope trade:futures:write required" } }

Fix: Create a new key with the required scope at Dashboard → API Keys.

403 Forbidden — Exchange credentials missing

You're calling a trading or account endpoint but haven't added exchange credentials.

Fix: Go to Dashboard → Exchanges and add your exchange API credentials.

Rate Limiting

429 Too Many Requests

You've exceeded your monthly quota.

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

Fix: Wait until the reset timestamp. For automated systems, implement exponential backoff:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const resetTime = Number(response.headers.get('X-RateLimit-Reset'));
    const waitMs = resetTime * 1000 - Date.now();
    await new Promise((resolve) => setTimeout(resolve, Math.max(waitMs, 1000)));
  }
  throw new Error('Rate limit exceeded after retries');
}

Consistently hitting limits

Reduce request frequency by caching static data (pairs, timeframes), or upgrade your plan at Dashboard → Billing.

Exchange Errors

"Exchange not supported"

Use one of the 12 supported exchanges: binance, bybit, okx, kucoin, gate, htx, bitget, bingx, bitmart, bitmex, coinex, hyperliquid.

"Symbol not found"

The trading pair doesn't exist on the specified exchange and market type.

Fix: Call GET /market/pairs to list available pairs for that exchange and market type.

"Insufficient balance"

Your exchange account doesn't have enough funds for the order.

Fix: Check balance with GET /account/balance or deposit funds on the exchange directly.

Exchange maintenance

Exchanges occasionally go offline. GoldenClaw returns a 502 or 503 error.

Fix: Wait and retry. Check the exchange's official status page.

MCP Connection Issues

Tools not appearing

1. Verify URL: https://stage.goldenclaw.sh/mcp
2. Check the Authorization header is set correctly
3. Restart your AI client after changing the config
4. Check client logs for connection errors

"Transport error" or "Connection failed"

Network issue between your client and GoldenClaw.

Fix: Check your internet connection. Verify the URL has the https:// prefix. Check if a firewall or proxy is blocking the connection.

MCP connects but tools fail

The connection works but individual tool calls return errors.

Common causes:

• Missing exchange credentials (for trading/account tools)
• Invalid parameters (wrong symbol format, unsupported timeframe)
• Insufficient API key scopes

Data Issues

OHLCV data seems stale or empty

Some exchanges have limited historical data for certain pairs or timeframes.

Fix: Try a popular pair (BTC/USDT) or standard timeframe (1h, 4h, 1d) to verify.

Indicator returns unexpected values

Check that you're using the correct timeframe, period, and category. Indicators need sufficient historical data — request at least 2× the indicator period in candles.

Price differs between exchanges

Expected behavior. Each exchange has its own order book. Prices can vary by 0.1-0.5% across exchanges.

Still Need Help?

• API Reference — Endpoint details and response formats
• Best Practices — Rate limiting and error handling patterns
• Contact support@goldenclaw.sh