REST API

Access the AIXBT API using API key authentication. For pay-per-request access without API keys, see x402.

Authentication

Most endpoints require an API key. Include it in the x-api-key header:

curl "https://api.aixbt.tech/v2/projects" \
  -H "x-api-key: YOUR_API_KEY"

The grounding endpoint is the exception. It serves real-time data without authentication, providing market context across crypto, macro, traditional finance, and geopolitics.

Access Levels

Level	Authentication	Data	Rate Limits	How to Get
Grounding	None required	Real-time (grounding only)	10/min, 300/day	Just call the API
x402 Key	`x-api-key` header	Real-time	30/min, 10k/day	Purchase via x402 - from $10/day
Full Key	`x-api-key` header	Real-time	100/min, 100k/day	Data, Pro, or Holder plan

Requests to data endpoints without an API key receive a 403 response with an API_KEY_REQUIRED error code and upgrade information (see Error Responses). x402 keys are convenient for short-term use; for ongoing access, a subscription plan offers the same or better value with higher rate limits. For the agentic endpoint (Indigo), an API key is required. Use x402 pay-per-request or a subscription key.

Quick Start

Grounding (No Key Required)

The grounding endpoint provides real-time market context without authentication:

curl "https://api.aixbt.tech/v2/grounding"

Projects (Key Required)

Data endpoints require an API key in the x-api-key header:

curl "https://api.aixbt.tech/v2/projects?limit=5" \
  -H "x-api-key: YOUR_API_KEY"

A successful response returns:

{
  "status": 200,
  "data": [...],
  "pagination": { "page": 1, "limit": 5, "totalCount": 1000, "hasMore": true }
}

Requests without an API key to data endpoints return 403 with upgrade information. See Getting Started for access options.

API Key Info

GET /v2/api-keys/info

Returns metadata about the API key used to authenticate the request.

{
  "status": 200,
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "type": "x402",
    "scopes": ["mcp", "projects"],
    "expiresAt": "2026-03-27T08:00:00.000Z"
  }
}

The expiresAt field returns "never" if the key has no expiration set.

Rate Limits

	Grounding (no key)	x402 (personal)	Full (subscription)
Per minute	10	30	100
Per day	300	10,000	100,000

Rate Limit Headers

Every response includes headers showing your current usage:

X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 99
X-RateLimit-Reset-Minute: 2025-01-15T12:01:00.000Z
X-RateLimit-Limit-Day: 100000
X-RateLimit-Remaining-Day: 99999
X-RateLimit-Reset-Day: 2025-01-16T00:00:00.000Z

Rate Limit Exceeded

When you exceed a limit, you'll receive a 429 response:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded (minute). Try again after 2025-01-15T12:01:00.000Z",
  "code": "RATE_LIMIT_EXCEEDED",
  "limitType": "minute"
}

The response includes a Retry-After header with the number of seconds to wait.

Response Format

All endpoints return a consistent JSON structure:

Success Response

{
  "status": 200,
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 1000,
    "hasMore": true
  }
}

The pagination object is included for list endpoints.

Unauthenticated Error Response

Data endpoints called without an API key return a 403 response with upgrade information:

{
  "error": "Forbidden",
  "message": "An API key is required to access this endpoint. Visit docs.aixbt.tech for access options.",
  "code": "API_KEY_REQUIRED",
  "meta": {
    "upgrade": {
      "description": "Purchase an API key for real-time access - no account needed.",
      "protocol": "x402",
      "payment": "USDC on Base",
      "options": [
        { "period": "1 day", "price": "$10", "method": "POST", "url": "https://api.aixbt.tech/x402/v2/api-keys/1d" },
        { "period": "1 week", "price": "$50", "method": "POST", "url": "https://api.aixbt.tech/x402/v2/api-keys/1w" },
        { "period": "4 weeks", "price": "$100", "method": "POST", "url": "https://api.aixbt.tech/x402/v2/api-keys/4w" }
      ]
    }
  }
}

This applies to all data endpoints (/v2/projects, /v2/signals, /v2/projects/{id}, etc.).

Reference endpoints (/v2/clusters, /v2/projects/chains) and grounding remain accessible without a key. Grounding responses include a meta.upgrade block when unauthenticated.

Error Response

{
  "status": 400,
  "error": "Invalid request parameters",
  "data": []
}

HTTP Status Codes

Status	Code	Meaning
`200`	-	Success
`400`	-	Bad request, check your parameters
`401`	`INVALID_API_KEY`	API key is invalid, expired, or inactive
`403`	`API_KEY_REQUIRED`	No API key provided (includes upgrade info)
`403`	`INVALID_API_KEY_SCOPE`	API key lacks required permissions
`404`	-	Resource not found
`429`	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded
`500`	-	Server error

Pagination

List endpoints support pagination with these query parameters:

Parameter	Default	Max	Description
`page`	1	-	Page number (1-indexed)
`limit`	50	50	Results per page

Example:

curl "https://api.aixbt.tech/v2/projects?page=2&limit=25" \
  -H "x-api-key: YOUR_API_KEY"

Filtering

Most list endpoints support filtering. Filters use AND logic between different parameters, and OR logic for multiple values within a parameter.

# Projects matching (name=eth OR name=btc) AND chain=base
curl "https://api.aixbt.tech/v2/projects?names=eth,btc&chain=base" \
  -H "x-api-key: YOUR_API_KEY"

See the API Reference for available filters on each endpoint.

Next Steps

Getting Started - Access tiers and setup paths
API Reference - Complete endpoint documentation
x402 - Pay-per-request alternative

Base URL