Skip to main content

​
Base URL

The API gateway is accessible at: 
http://localhost:3000
For production deployments, configure your base URL accordingly.

​
API Versioning

All API endpoints are versioned and prefixed with /api/v1. Example: 
http://localhost:3000/api/v1/wallets

​
Required Headers

All API requests require authentication headers:
​
x-api-key
string
required
Your API key for authentication. Configured via API_GATEWAY_API_KEYS environment variable.
​
x-tenant-id
string
Optional tenant identifier for multi-tenant deployments. Use * for wildcard access.

​
Common Headers

curl -H "x-api-key: dev-api-key" \
     -H "Content-Type: application/json" \
     http://localhost:3000/api/v1/wallets

​
Response Envelope

All API responses follow a standardized envelope structure for consistent error handling: 
{
  "status": "success",
  "stage": "completed",
  "traceId": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    // Response payload
  }
}
See Response Format for detailed specifications.

​
HTTP Methods

The API uses standard HTTP methods:
  • GET - Retrieve resources
  • POST - Create resources or execute actions
  • PUT - Update existing resources
  • DELETE - Remove resources (limited use)

​
Rate Limiting

API requests are rate-limited per API key:
  • Default: 120 requests per minute
  • Configure via: API_GATEWAY_RATE_LIMIT_PER_MINUTE
  • Rate limit headers included in responses:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

​
Pagination

List endpoints support pagination via query parameters:
​
limit
number
default:"50"
Maximum number of items to return (max: 100)
​
offset
number
default:"0"
Number of items to skip
Example: 
curl -H "x-api-key: dev-api-key" \
     "http://localhost:3000/api/v1/wallets?limit=20&offset=40"

​
Idempotency

Transaction creation supports idempotency keys to prevent duplicate operations: 
{
  "walletId": "uuid",
  "type": "transfer_sol",
  "protocol": "system-program",
  "idempotencyKey": "unique-operation-id-12345",
  "intent": {
    "destination": "...",
    "lamports": 1000000
  }
}
When an idempotency key is provided, repeated requests return the original transaction record.

​
Health Check

Verify API availability: 
curl http://localhost:3000/health
Response: 
{
  "status": "ok",
  "timestamp": "2026-03-08T12:00:00.000Z"
}

​
SDK Support

TypeScript SDK available at packages/sdk: 
import { createAgenticWalletClient } from '@agentic-wallet/sdk';

const client = createAgenticWalletClient(
  'http://localhost:3000',
  {
    apiKey: 'dev-api-key',
    tenantId: 'my-tenant'
  }
);

// Use typed methods
const wallet = await client.wallet.create({ label: 'my-wallet' });

​
Next Steps

Authentication

Learn about API key and scope management

Response Format

Understand the response envelope structure

Errors

Handle errors and error codes

Wallets

Start with wallet operations

Build docs developers (and LLMs) love

Get started for freeTalk to us