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..."

You can also use the 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"
  }'

Response:

{
  "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"

Until verified, any request using the key will return 401 Unauthorized.

Key rotation

curl -X POST https://backend.inkwell.finance/api/v1/agents/{id}/rotate \
  -H "Authorization: Bearer YOUR_JWT"

This invalidates the old key immediately and returns a new one.

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

When rate limited, the API returns 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

Self-registration always creates a free tier key. There is no automatic upgrade — tier promotion requires an admin to re-register the agent via 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
}

Standard error codes: invalid_input, rate_limited, store_not_ready, rpc_unavailable, not_found, unauthorized, forbidden, timeout, service_overloaded, internal_error.

Getting Started

IKA Staking (Agent)

IKA Staking (Public)

Agent Identity

Authentication

Authentication

API Key (Agent endpoints)

Getting a key

Email verification

Key rotation

Bearer Token (Management endpoints)

Public endpoints (no auth)

Rate limits

Limits by tier

Registration limits

Global protection

Error responses

​Authentication

​API Key (Agent endpoints)

​Getting a key

​Email verification

​Key rotation

​Bearer Token (Management endpoints)

​Public endpoints (no auth)

​Rate limits

​Limits by tier

​Registration limits

​Global protection

​Error responses

Authentication

API Key (Agent endpoints)

Getting a key

Email verification

Key rotation

Bearer Token (Management endpoints)

Public endpoints (no auth)

Rate limits

Limits by tier

Registration limits

Global protection

Error responses