Skip to main content

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.

​
Inkwell Agent API

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

​
What can agents do?

CapabilityEndpointsAuth
Stake IKA tokensCompute optimal allocation, build stake/unstake/withdraw transactionsAPI key
Analyze validatorsScored rankings, APY history, delegator listsAPI key (scored) or public
Rebalance positionsGet step-by-step rebalance plans for existing positionsAPI key (builder+)
Monitor networkEpoch data, validator set, IKA pricePublic
Manage identitySelf-register, rotate keys, view behavioral profileAPI 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.
TierValidators visibleRebalancingRPMRPDHow to get
freeTop 10No10100Self-register
builderTop 25Yes1001,000Self-register or admin
proAllYesCustomCustomAdmin only
enterpriseAllYesCustomCustomAdmin 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:
LayerWhat it does
Email verificationKeys are inactive until the registrant verifies email ownership
Per-agent rate limitsRPM and RPD limits enforced per API key, persisted across restarts
IP throttle100 requests/minute per IP regardless of agent identity
Circuit breaker503 if total API traffic exceeds 10,000 rpm
Registration limits3/hour + 10/day per IP, 100/day global cap
HMAC-SHA256 key hashingAPI keys are hashed with a server secret — DB theft alone is insufficient
Audit loggingEvery request logged with timestamp, agent ID, endpoint, status, and latency
Request timeout10 second hard limit per request
Body size limit100KB 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.