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.
Authentication
The Inkwell Agent API uses two authentication methods depending on the endpoint.
API Key (Agent endpoints)
All /api/v1/ika/agent/* endpoints require an API key in the X-API-Key header. Keys are prefixed with lev_.
curl https://backend.inkwell.finance/api/v1/ika/agent/validators/scored \
-H "X-API-Key: lev_abc123..."
Authorization: Bearer header:
curl https://backend.inkwell.finance/api/v1/ika/agent/validators/scored \
-H "Authorization: Bearer lev_abc123..."
Getting a key
Self-register (no account needed):
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"
}'
{
"success": true,
"data": {
"apiKey": "lev_abc123...",
"keyPrefix": "lev_abc12345",
"tier": "free",
"status": "pending_verification",
"rateLimits": { "rpm": 10, "rpd": 100 },
"warning": "Store this key securely. It cannot be retrieved again. Check your email to verify and activate it."
}
}
Your key is returned immediately but inactive until you verify your email. Check your inbox for a verification link from Inkwell. The link expires after 24 hours.
Store your API key securely. It cannot be retrieved after creation. If lost, use key rotation to generate a new one.
Email verification
After registering, click the verification link sent to your email. You can also verify programmatically:
curl "https://backend.inkwell.finance/api/v1/agents/verify?token=YOUR_VERIFICATION_TOKEN"
401 Unauthorized.
Key rotation
curl -X POST https://backend.inkwell.finance/api/v1/agents/{id}/rotate \
-H "Authorization: Bearer YOUR_JWT"
Bearer Token (Management endpoints)
Agent management endpoints (/api/v1/agents/* except self-register and verify) require a user JWT:
curl https://backend.inkwell.finance/api/v1/agents \
-H "Authorization: Bearer YOUR_JWT"
Public endpoints (no auth)
All /api/v1/ika/* endpoints (without /agent/) are public and require no authentication:
curl https://backend.inkwell.finance/api/v1/ika/validators
curl https://backend.inkwell.finance/api/v1/ika/price
curl https://backend.inkwell.finance/api/v1/ika/epoch
Rate limits
Rate limit headers are included on every authenticated response:
| Header | Description |
|---|
X-RateLimit-Remaining | Requests remaining (min of RPM and RPD) |
X-RateLimit-Reset | Unix timestamp when the minute window resets |
429 Too Many Requests with a Retry-After header.
Rate limits are persisted — restarting the server does not reset your limits.
Limits by tier
| Tier | RPM | RPD | How to get |
|---|
| free | 10 | 100 | Self-register |
| builder | 100 | 1,000 | Self-register or admin |
| pro | Custom | Custom | Admin only |
| enterprise | Custom | Custom | Admin only |
POST /agents/register.
Registration limits
Self-registration is rate limited to prevent abuse:
| Limit | Value |
|---|
| Per IP per hour | 3 registrations |
| Per IP per day | 10 registrations |
| Global daily cap | 100 registrations |
Global protection
The API includes a global circuit breaker. If total request volume exceeds 10,000 requests per minute across all agents, the API returns 503 Service Overloaded until traffic subsides. Individual IP addresses are also throttled at 100 requests per minute regardless of agent identity.
Error responses
All errors follow a consistent format:
{
"error": "rate_limited",
"message": "Per-minute rate limit exceeded (10 rpm)",
"status": 429
}
invalid_input, rate_limited, store_not_ready, rpc_unavailable, not_found, unauthorized, forbidden, timeout, service_overloaded, internal_error.
