API Overview

The Steward API is a REST API built with Hono running on Bun. All responses follow a consistent ApiResponse<T> shape.

Base URL

Steward is self-hosted. Point the SDK and all requests at your own deployment. The default local Compose profile exposes the API on port 3200:

http://localhost:3200

Replace this with your deployment’s URL when running behind your own domain and TLS.

Authentication

Steward supports three authentication methods:

Tenant API Key
Agent JWT
SIWE (Sign In With Ethereum)

For tenant-level operations (agent CRUD, policy management, secret management):

curl http://localhost:3200/agents \
  -H "X-Steward-Key: stwd_your_tenant_api_key"

The API key is returned once when a tenant is created and cannot be retrieved again.

For agent-scoped operations (signing, balance checks). Preferred for agents:

curl http://localhost:3200/vault/my-agent/sign \
  -H "Authorization: Bearer stwd_jwt_..."

Generate agent tokens via POST /agents/:agentId/token (requires tenant auth).

For web dashboard authentication:

# 1. Get nonce
curl http://localhost:3200/auth/nonce

# 2. Sign message and verify
curl -X POST http://localhost:3200/auth/verify \
  -H "Content-Type: application/json" \
  -d '{ "message": "...", "signature": "0x..." }'

Returns a session JWT. Auto-creates a tenant on first sign-in.

Platform Key

For platform-level operations (cross-tenant management), use the platform key:

curl http://localhost:3200/platform/stats \
  -H "X-Steward-Platform-Key: your-platform-key"

Response Format

All endpoints return a consistent format:

// Success
{
  "ok": true,
  "data": T  // Response payload
}

// Error
{
  "ok": false,
  "error": "Human-readable error message",
  "data"?: T  // Optional additional context (e.g., policy results)
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created (new resource)
202	Accepted (transaction queued for approval)
400	Bad request (invalid input)
401	Unauthorized (missing or invalid auth)
403	Forbidden (policy denied, wrong scope)
404	Not found
409	Conflict (duplicate resource)
429	Too many requests
500	Internal server error
502	Bad gateway (RPC error from blockchain)

Rate Limits

Both Bun and Workers enforce the global per-client request limit through Redis in production, so replicas and restarts share one budget. A guaranteed single-instance Bun deployment may explicitly acknowledge a restart-resetting memory limiter; development and test use bounded memory by default. Sensitive wallet routes can also enforce Redis-backed per-agent limits via policies. Rate-limited responses return 429 with Retry-After, standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers, plus legacy X-RateLimit-* compatibility headers. Successful wallet-action responses that evaluate a rate-limit policy include the same standard remaining budget headers without Retry-After.

Request Hardening Inventory

The generated OpenAPI contract marks sensitive mutating operations with x-steward-hardening. These operations are under the same sensitive-prefix inventory used by the request-expiry and authorization-signature middleware. For these routes:

X-Steward-Request-Timestamp or X-Steward-Request-Expires-At is required when request-expiry enforcement is enabled.
X-Steward-Signature is required when authorization signatures are enabled. The header accepts HMAC v1= signatures and P-256 p256= signatures.
X-Steward-Signing-Key-Id can select a managed tenant request-signing key.
Idempotency-Key is required for signed sensitive requests and recommended for all sensitive mutations.

OpenAPI also lists these headers as optional parameters because enforcement is deployment-configurable; the x-steward-hardening extension records when they become mandatory.

Idempotency and safe retries

For fund-moving or signing workflows, include a caller-stable referenceId in the request body when the endpoint supports it, and send an Idempotency-Key header for sensitive mutations where your deployment accepts or requires one. Use the same values when retrying after client timeouts so transaction history, audit events, and lifecycle webhooks can be correlated to one business operation. Bitcoin PSBT signing is sign/finalize-only: POST /vault/:agentId/sign-bitcoin-psbt returns Steward’s transactionId, may return finalized raw transaction metadata when finalize: true, and never broadcasts. Because the route enforces fee caps and spend/address policies before signing, clients should query by referenceId before creating replacement PSBT requests. If a finalized raw transaction was already handed to a broadcaster, do not retry that broadcast blindly; check the Bitcoin txId with your broadcaster or indexer first.

Route Groups

Prefix	Description	Auth Required
`/agents`	Agent CRUD + policy management	Tenant key or agent JWT
`/accounts`	Digital asset account resources grouping tenant wallets	Tenant key
`/user/me/wallet`	Authenticated user-wallet provisioning, indexed wallets, and additional signers	Personal user session
`/vault`	Signing, approvals, history	Agent JWT or tenant key
`/audit`	Tenant audit events and action-history filters	Owner/admin session + recent MFA
`/secrets`	Secret + route CRUD	Tenant key only
`/condition-sets`	Reusable policy allow/block list CRUD and item management	Tenant owner/admin session
`/tenants`	Tenant management	Tenant key
`/auth`	SIWE, passkeys, email login	Varies
`/platform`	Cross-tenant admin	Platform key
`/health`	Health check	None

Content Type

All request bodies must be JSON:

Content-Type: application/json

Error Handling

import { StewardClient, StewardApiError } from "@stwd/sdk";

try {
  await steward.signTransaction("my-agent", { ... });
} catch (error) {
  if (error instanceof StewardApiError) {
    console.error(`Status: ${error.status}`);
    console.error(`Message: ${error.message}`);
    console.error(`Data:`, error.data); // May contain policy results
  }
}

​API Overview

​Base URL

​Authentication

​Platform Key

​Response Format

​HTTP Status Codes

​Rate Limits

​Request Hardening Inventory

​Idempotency and safe retries

​Route Groups

​Content Type

​Error Handling