> ## Documentation Index
> Fetch the complete documentation index at: https://docs.defiorbit.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# For AI agents

> The DeFi Orbit API contract on one page: auth, retries, credits, pagination, and MCP.

Everything an AI agent needs to call the DeFi Orbit API, on one page. For tool-based access, skip the REST API entirely and connect to [DeFi Orbit AI](/recipes/mcp) over MCP.

## The contract

* Base URL: `https://api.defiorbit.xyz`. Every route is under `/v1`.
* Auth: `Authorization: Bearer do_sk_...` on every request. The key selects the organization; credits and the rate limit are organization-level.
* Every success is JSON with `data` and `request_id`. Every failure is `{ "error": { "code", "message", "request_id" } }`.
* Only 2xx responses spend credits. Costs run 1–30 credits per call; each endpoint page in the [API Reference](/api-reference/uniswap-v3/summary) states its cost, and [Credits](/credits) has the billing rules.

## Retry rules

| Status | Action |
| - | - |
| `429` | Wait `Retry-After` seconds, then retry. |
| `502`, `503`, `504` | Retry with exponential backoff. |
| `400`, `401`, `402`, `403`, `404` | Do not retry. Fix the request, the key, or the balance first. |

The rate limit is 5 requests per second per organization by default. `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix seconds) are set on `429`.

## Protect the credit balance

Before loops or batch work, read the balance with `GET /v1/usage/credits` (1 credit). List and batch calls multiply a unit cost by result counts — read [Credits](/credits) before writing a loop. Start with `summary` endpoints (1–3 credits) to decide whether a deeper call is worth it.

## Pagination

List endpoints return `pagination` with `page`, `limit` (max 25), `total`, and absolute `next_page` / `prev_page` URLs. Follow `next_page` until it is `null`.

## Connect over MCP instead

```json theme={null}
{
  "mcpServers": {
    "defiorbit": {
      "url": "https://mcp.orbitcontrol.xyz/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}
```

Same key, same credits, same rate limit; 52 read-only tools. The full list is on the [tool reference](/ai/tools).

## Machine-readable docs

* OpenAPI spec: [`/openapi.yaml`](https://docs.defiorbit.xyz/openapi.yaml)
* Docs index for LLMs: [`/llms.txt`](https://docs.defiorbit.xyz/llms.txt) · full docs in one file: [`/llms-full.txt`](https://docs.defiorbit.xyz/llms-full.txt)
* Every page has a raw markdown twin: append `.md` to its URL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.