API Reference
REST API for programmatic access to ChainGraph data and features.
Base URL
https://app.chain-graph.com/api/v1
Authentication
All API requests require a valid session token passed as a cookie or Bearer token. Obtain a token by authenticating via the /api/v1/auth/login endpoint.
# Cookie-based (browser)
Cookie: session_token=eyJhbG...
# Bearer token (API clients)
Authorization: Bearer eyJhbG...
Anonymous endpoints (Explorer lookups, shared investigations) work without authentication but are subject to IP-based rate limits.
Endpoints
Health
| Method | Path | Description |
|---|
| GET | /health | Service health check |
| GET | /health/ready | Readiness check (all dependencies) |
Auth
| Method | Path | Description |
|---|
| POST | /auth/login | Exchange Firebase token for session |
| POST | /auth/logout | Invalidate current session |
| GET | /auth/me | Get current user info |
Explorer
| Method | Path | Description |
|---|
| GET | /chain/address/{address} | Address summary |
| GET | /chain/tx/{hash} | Transaction details |
| GET | /chain/block/{number} | Block details |
| GET | /chain/search?q=... | Universal search |
Investigations
| Method | Path | Description |
|---|
| GET | /investigations | List investigations |
| POST | /investigations | Create investigation |
| GET | /investigations/{id} | Get investigation |
| PATCH | /investigations/{id} | Update investigation |
| DELETE | /investigations/{id} | Delete investigation |
| POST | /investigations/{id}/nodes | Add node |
| POST | /investigations/{id}/edges | Add edge |
| POST | /investigations/{id}/share | Generate share link |
| POST | /investigations/{id}/export | Export investigation |
Graph Queries
| Method | Path | Description |
|---|
| POST | /graph/cypher | Execute Cypher query |
| POST | /graph/expand/{address} | Expand address connections |
SQL Queries
| Method | Path | Description |
|---|
| POST | /sql | Execute SQL query |
| GET | /sql/tables | List available tables |
Labels
| Method | Path | Description |
|---|
| GET | /labels?address=... | Get labels for address |
| POST | /labels | Create custom label |
| DELETE | /labels/{id} | Delete custom label |
Monitors
| Method | Path | Description |
|---|
| GET | /monitors | List monitors |
| POST | /monitors | Create monitor |
| PATCH | /monitors/{id} | Update monitor |
| DELETE | /monitors/{id} | Delete monitor |
Error format
{
"detail": "Human-readable error message"
}
HTTP status codes follow standard REST conventions: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests, 500 Internal Server Error.
Rate limits
API rate limits are per-user (authenticated) or per-IP (anonymous). Exceeding limits returns a 429 response with a Retry-After header.
Interactive docs
Full Swagger/OpenAPI documentation with “Try it” functionality is available at app.chain-graph.com/api/v1/docs.