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