API reference

WalletKit REST API

All endpoints use https://api.alloy.build as the base URL (or https://sandbox.api.alloy.build for sandbox).

OpenAPI JSON

Generated Swagger artifact for API clients and tools.

OpenAPI YAML

Human-readable API contract source.

Version matrix

Trace SDK, OpenAPI, and contract versions.

Rendered Mesh contract explorer

Browse the current proto-derived Mesh routes, required metadata headers, request fields, response fields, and HSM signing examples without loading a separate Swagger viewer.

Open Mesh contract explorer

Authentication

All requests require a Bearer token. Use API keys for server integrations and agent tokens for AI agents.

Authorization: Bearer <your-api-key-or-agent-token>

Providers

POST /v1/providers/connect
GET /v1/providers
GET /v1/providers/:id
DELETE /v1/providers/:id

Wallets

POST /v1/wallets
GET /v1/wallets
GET /v1/wallets/:id
PATCH /v1/wallets/:id
POST /v1/wallets/:id/archive

Transaction Intents

POST /v1/wallets/:id/transaction-intents
GET /v1/wallets/:id/transaction-intents
GET /v1/wallets/:id/transaction-intents/:txId
POST /v1/wallets/:id/transaction-intents/:txId/approve
POST /v1/wallets/:id/transaction-intents/:txId/reject

Policies

POST /v1/policies
GET /v1/policies
GET /v1/policies/:id
POST /v1/policies/:id/evaluate
GET /v1/policies/:id/decisions

Events & Webhooks

GET /v1/events
GET /v1/events/:id
POST /v1/webhooks
GET /v1/webhooks
DELETE /v1/webhooks/:id

Agent Tokens

POST /v1/agent-tokens
GET /v1/agent-tokens
DELETE /v1/agent-tokens/:id

Error codes

All errors return a structured JSON body with error, code, and message fields, plus optional details for validation errors.

{
  "error": "policy_rejected",
  "code": 422,
  "message": "Transaction exceeds daily limit of 50,000 USDC",
  "details": {
    "policy_id": "pol_daily_limit",
    "evaluated_amount": "75000.00",
    "limit": "50000.00",
    "suggestion": "Split into multiple transactions or request limit increase"
  }
}
Status Code Description
400 bad_request Malformed request body or invalid parameters
401 unauthorized Missing or invalid API key / agent token
403 forbidden Token lacks required scope for this action
404 not_found Resource does not exist
409 conflict Idempotency key collision or state conflict
422 policy_rejected Transaction rejected by policy evaluation
429 rate_limited Too many requests — see rate limits below
500 internal_error Unexpected server error — retry with backoff

Rate limits

Tier Read Write
Sandbox100 req/min20 req/min
Starter1,000 req/min200 req/min
EnterpriseCustomCustom

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Webhooks

Alloy sends normalized webhook events for transaction state changes, policy decisions, risk alerts, and reconciliation updates — regardless of the underlying provider.

Event types

transaction.created Intent submitted
transaction.approved Policy + risk passed
transaction.confirmed On-chain confirmation
transaction.failed Provider or chain failure
policy.violation Policy rule violated
risk.alert Risk threshold exceeded

Signature verification

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}