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

# API Overview

> Build AI agents that interact with IKA staking and Leviathan protocol services.

# Inkwell Agent API

The Inkwell Agent API lets AI agents programmatically interact with IKA staking infrastructure and Leviathan protocol services.

## What can agents do?

| Capability              | Endpoints                                                             | Auth                       |
| ----------------------- | --------------------------------------------------------------------- | -------------------------- |
| **Stake IKA tokens**    | Compute optimal allocation, build stake/unstake/withdraw transactions | API key                    |
| **Analyze validators**  | Scored rankings, APY history, delegator lists                         | API key (scored) or public |
| **Rebalance positions** | Get step-by-step rebalance plans for existing positions               | API key (builder+)         |
| **Monitor network**     | Epoch data, validator set, IKA price                                  | Public                     |
| **Manage identity**     | Self-register, rotate keys, view behavioral profile                   | API key or JWT             |

## Quick start

### 1. Get an API key

```bash theme={null}
curl -X POST https://backend.inkwell.finance/api/v1/agents/self-register \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com", "agentName": "my-staking-bot"}'
```

Your key is returned immediately but inactive. Check your email and click the verification link to activate it (expires in 24 hours).

### 2. Get scored validators

```bash theme={null}
curl https://backend.inkwell.finance/api/v1/ika/agent/validators/scored \
  -H "X-API-Key: YOUR_KEY"
```

### 3. Compute an allocation

```bash theme={null}
curl -X POST https://backend.inkwell.finance/api/v1/ika/agent/allocate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": "10000000000", "maxValidators": 5}'
```

### 4. Build a stake transaction

```bash theme={null}
curl -X POST https://backend.inkwell.finance/api/v1/ika/agent/tx/stake \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"validatorId": "0x...", "amount": "5000000000"}'
```

The response contains Move call parameters. Your agent signs and submits the transaction using the Sui SDK.

## Agent tiers

Every API key belongs to a tier that determines rate limits, data access, and feature availability.

| Tier           | Validators visible | Rebalancing | RPM    | RPD    | How to get             |
| -------------- | ------------------ | ----------- | ------ | ------ | ---------------------- |
| **free**       | Top 10             | No          | 10     | 100    | Self-register          |
| **builder**    | Top 25             | Yes         | 100    | 1,000  | Self-register or admin |
| **pro**        | All                | Yes         | Custom | Custom | Admin only             |
| **enterprise** | All                | Yes         | Custom | Custom | Admin only             |

### How tiers work

* **Self-registration** (`POST /agents/self-register`) always creates a **free** tier key with read-only permissions.
* **Admin registration** (`POST /agents/register`) can create keys at any tier. Non-admin users are capped at **builder**.
* Requesting `pro` or `enterprise` without admin privileges returns `403`.
* There is no automatic upgrade path — tier promotion requires an admin to re-register the agent.

### What changes per tier

* **Scored validators** (`GET /validators/scored`): Free tier sees the top 10 validators by composite score. Builder sees top 25. Pro and enterprise see all.
* **Rebalance planning** (`POST /rebalance-plan`): Returns `403 Forbidden` for free tier agents. Requires builder or higher.
* **Rate limits**: Free tier is hard-capped at 10 requests/minute and 100/day. Builder gets 100 rpm / 1,000 rpd. Pro and enterprise have custom limits set by an admin.

## Security

The API includes multiple layers of protection:

| Layer                       | What it does                                                                 |
| --------------------------- | ---------------------------------------------------------------------------- |
| **Email verification**      | Keys are inactive until the registrant verifies email ownership              |
| **Per-agent rate limits**   | RPM and RPD limits enforced per API key, persisted across restarts           |
| **IP throttle**             | 100 requests/minute per IP regardless of agent identity                      |
| **Circuit breaker**         | 503 if total API traffic exceeds 10,000 rpm                                  |
| **Registration limits**     | 3/hour + 10/day per IP, 100/day global cap                                   |
| **HMAC-SHA256 key hashing** | API keys are hashed with a server secret — DB theft alone is insufficient    |
| **Audit logging**           | Every request logged with timestamp, agent ID, endpoint, status, and latency |
| **Request timeout**         | 10 second hard limit per request                                             |
| **Body size limit**         | 100KB max request body                                                       |

All enforcement is server-side. Keys are prefixed with `lev_`.

## Integration options

<CardGroup cols={3}>
  <Card title="REST API" icon="code" href="/api-reference/authentication">
    Direct HTTP calls with API key authentication.
  </Card>

  <Card title="MCP Server" icon="robot" href="/api-reference/skill-installer">
    Model Context Protocol server for Claude and other MCP clients.
  </Card>

  <Card title="Claude Code Skill" icon="wand-magic-sparkles" href="/api-reference/skill-installer">
    Native Claude Code skill for interactive staking workflows.
  </Card>
</CardGroup>