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

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

curl https://backend.inkwell.finance/api/v1/ika/agent/validators/scored \
  -H "X-API-Key: YOUR_KEY"

3. Compute an allocation

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

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

REST API

Direct HTTP calls with API key authentication.

MCP Server

Model Context Protocol server for Claude and other MCP clients.

Claude Code Skill

Native Claude Code skill for interactive staking workflows.

Getting Started

IKA Staking (Agent)

IKA Staking (Public)

Agent Identity

API Overview

Inkwell Agent API

What can agents do?

Quick start

1. Get an API key

2. Get scored validators

3. Compute an allocation

4. Build a stake transaction

Agent tiers

How tiers work

What changes per tier

Security

Integration options

REST API

MCP Server

Claude Code Skill

​Inkwell Agent API

​What can agents do?

​Quick start

​1. Get an API key

​2. Get scored validators

​3. Compute an allocation

​4. Build a stake transaction

​Agent tiers

​How tiers work

​What changes per tier

​Security

​Integration options

REST API

MCP Server

Claude Code Skill

Inkwell Agent API

What can agents do?

Quick start

1. Get an API key

2. Get scored validators

3. Compute an allocation

4. Build a stake transaction

Agent tiers

How tiers work

What changes per tier

Security

Integration options