# REST API

Everything the MCP server can do is also a plain HTTPS API, so you can build dashboards, bots and backfills without an MCP client.

**Base URL** `https://data.stalkchain.com/api/v1` · **Auth** `Authorization: Bearer sc_your_key` (API key from the dashboard) or an OAuth access token.

## Call a tool

```bash
curl -X POST https://data.stalkchain.com/api/v1/tools/stalkchain_fomo_kol_holders \
  -H "Authorization: Bearer sc_your_key" \
  -H "content-type: application/json" \
  -d '{"address":"0x5e55f18453545d0d4314c5106a2d8db934298e95","chain":"robinhood"}'
```

GET works too, with inputs as query parameters (numbers and booleans are coerced):

```
GET /api/v1/tools/stalkchain_fomo_leaderboard?window=24h&limit=10
```

## Response shape

```json
{
  "data": { "...": "tool output" },
  "notes": ["optional caveats, e.g. a part that timed out upstream"],
  "credits": { "creditsSpent": 500, "calls": 2, "cachedCalls": 0, "endpoints": ["/token/…/holders", "/v2/token/…/stats"], "remaining": 1249500 },
  "meta": { "tool": "stalkchain_fomo_kol_holders", "generatedAt": "2026-09-23T09:10:00.000Z", "durationMs": 640 }
}
```

`x-credits-remaining` is also sent as a response header.

## Other endpoints

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/v1/tools` | List every tool with its JSON-schema inputs |
| GET | `/api/v1/me` | Your balance, calls left and usage by tool |
| GET | `/api/v1/openapi.json` | OpenAPI 3.1 document (also rendered under **API Reference**) |

## Errors

All errors are `{ "error": { "code", "message" } }`.

| HTTP | code | Meaning |
|---|---|---|
| 400 | `invalid_request` | Inputs failed validation; `issues` lists what |
| 401 | `unauthorized` | Missing or revoked key / token |
| 402 | `out_of_credits` | Buy a pack; the next call works immediately |
| 404 | `not_found` | Unknown tool or route |
| 429 | `rate_limited` | Slow down (only for unauthenticated calls) |
| 502 | `tool_error` | The tool ran but the upstream failed; `details` has the tool's own message |

See [Errors and retries](/guides/errors) for what to do on each.