# Using with AI Agents

There are three ways to use Arkham with an AI assistant or agent:

| You want to | Use |
| --- | --- |
| Ask Claude or Codex questions and get live Arkham data | [MCP Server](/add-ons/mcp) |
| Have a coding agent write code that calls the Arkham API | [Docs for coding agents](#docs-for-coding-agents) |
| Let an agent pay per request, with no account or API key | [x402](/add-ons/x402-agent-payments) |

## MCP Server

The quickest way to start. Add Arkham to your assistant once, then ask questions in plain English. Setup takes about a minute: see [MCP Server](/add-ons/mcp).

## Docs for Coding Agents

If an agent is writing code against the API, give it the documentation. The full Arkham API docs are one text file, [arkm.com/llms-full.txt](https://arkm.com/llms-full.txt), updated automatically whenever the docs change. This is separate from the MCP server: the file teaches the agent the API, while MCP lets it fetch live data.

Give it to your agent by pasting the link into your prompt:

> _"Read https://arkm.com/llms-full.txt, then write a Python script that lists the top holders of a token."_

::: tip Claude Projects
Download `llms-full.txt` and upload it to your project's knowledge so every chat in the project knows the API. Add the [Arkham connector](/add-ons/mcp) too for live data.
:::

::: tip Tips
- Ask the agent to use only endpoints from the Arkham docs, and to say which one it's calling.
- `/transfers` is billed per row returned, so ask for small result sets.
:::

## Costs and Overage

How an agent is billed depends on how it pays:

- **With x402**, the agent pays in USDC for each request at its listed price. There is no allowance and no overage, and the agent can't spend more than its wallet holds.
- **With your API key**, through MCP or code it writes or runs, its requests draw on your subscription the same way your own requests do. Your tier includes a set number of credits per month. **Anything beyond that is billed as overage at your tier's price per overage credit, or your contracted rate, and access is not paused.** An agent that loops, retries, or pages through a large result set can run up overage without you noticing. See [Credit Pricing](/usage/credit-pricing) for overage and spending limits.

The steps and template below are for agents that use your API key.

Before you let an agent run unattended:

1. **Set a spending limit** on the [API Dashboard](https://arkm.com/api-dashboard). An overage cap of `$0` stops the agent once your included credits are used up.
2. **Give the agent a budget** in its project instructions (template below), so it estimates costs and checks with you before spending large amounts.
3. **Use a separate API key** for the agent, so you can revoke it without affecting your other integrations.

## Project Instructions Template

Paste this into the instructions file your agent reads: `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and other agents, or the project instructions of a Claude Project. Replace the values in angle brackets.

```markdown
## Arkham API

- API docs: https://arkm.com/llms-full.txt. Use only endpoints listed there.
- Credit costs: https://arkm.com/llms/guides/credit-pricing.md. Every request
  uses credits. Per-row endpoints (e.g. /transfers, /swaps) cost
  weight × rows returned.
- We are on the <tier> tier: <N> credits included per month. Usage beyond
  that is billed as overage at <$X> per credit. It is real money and
  access is not paused.

### Budget
- Budget for this project: <N> credits per <day | task>.
- Before running anything that makes more than <10> requests, or uses a
  per-row endpoint with limit > <100>, estimate the credits it will use
  (calls × weight, or rows × weight) and show me the estimate. Wait for my
  approval if it is more than <M> credits.
- Keep a running count of the credits you have spent in this project
  (calls × weight, or rows × weight) and stop when the budget is used up.
- Before a long or scheduled job, also check what the account has spent:
  GET https://api.arkm.com/analytics/endpoint-calls?start_date=<start>&end_date=<now>
  (free), with <start> rounded down to the start of a UTC hour. Add up
  totalCredits across dataPoints. This covers all of the account's usage,
  not just yours, and can lag by a few minutes.
- Never retry in an unbounded loop. On 402 or 403, stop and tell me: it
  means credits ran out or a spending limit was reached. Do not try to work
  around it.
- Use the smallest `limit` that answers the question, and cache results
  instead of fetching the same data again.
```