API Reference
Every endpoint lives under /api/v1.
Two auth modes. API key for signers. JWT session cookie for the dashboard. Some endpoints (signer list, audit log) accept either.
Authentication
API Key (Signer)
JWT Session (Dashboard)
Pass the signer’s API key in the x-api-key header. Generated during signer creation.curl -H "x-api-key: your-api-key" \
https://api.agentaos.ai/api/v1/sign/session
Authenticate via passkey (WebAuthn). The server returns a JWT session cookie.# 1. Get challenge, sign with wallet, then:
curl -X POST https://api.agentaos.ai/api/v1/auth/passkey/login \
-H "Content-Type: application/json" \
-d '{"credential": "..."}'
# Session cookie is set automatically
Signer-Facing Endpoints
API key auth. These are what your agent or CLI calls.
| Method | Path | Purpose |
|---|
POST | /sign/session | Start interactive Signer+Server signing session |
POST | /sign/round | Exchange CGGMP24 protocol messages |
POST | /sign/complete | Finalize signing and broadcast transaction |
POST | /sign-message/session | Start interactive message signing session |
POST | /sign-message/complete | Finalize message signing, return (v, r, s) |
Signing is an interactive multi-round protocol. The client calls /sign/session once, then /sign/round repeatedly until the protocol completes, then /sign/complete to finalize. The full key is never reconstructed.
Dashboard-Facing Endpoints
JWT session auth. These power the dashboard UI.
Signer Management
| Method | Path | Purpose |
|---|
POST | /signers | Create a new signer (triggers DKG) |
GET | /signers | List all signers |
GET | /signers/:id | Get signer details |
PATCH | /signers/:id | Update signer (name, description) |
DELETE | /signers/:id | Delete signer |
POST | /signers/:id/pause | Pause signer (blocks all signing) |
POST | /signers/:id/resume | Resume paused signer |
GET | /signers/:id/balance | Get signer ETH balance |
POST | /signers/:id/simulate | Simulate transaction (gas estimate) |
POST | /signers/:id/regenerate-key | Rotate API key |
GET | /signers/:id/tokens | List tracked tokens |
GET | /signers/:id/token-balances | Get token balances |
POST | /signers/:id/tokens | Add token to tracking list |
DELETE | /signers/:id/tokens/:tokenId | Remove tracked token |
Guardrails (Rules Engine)
| Method | Path | Purpose |
|---|
GET | /signers/:id/policy | Get active guardrail policy |
PUT | /signers/:id/policy | Save and activate guardrail rules |
GET | /signers/:id/policy/draft | Get draft policy |
PUT | /signers/:id/policy/draft | Save policy as draft |
POST | /signers/:id/policy/activate | Activate the draft policy |
POST | /signers/:id/policy/backtest | Backtest policy against historical transactions |
Built-in Policies
Eight policy types you can stack on any signer. Each one is a hard constraint — if a transaction violates any active policy, the server refuses to co-sign.
| Method | Path | Purpose |
|---|
GET | /signers/:id/policies | List active policies for a signer |
POST | /signers/:id/policies | Create a policy |
PATCH | /policies/:id | Update policy config |
DELETE | /policies/:id | Delete policy |
| Type | What It Enforces |
|---|
spending_limit | Max value per transaction |
daily_limit | Max total spend per 24h |
monthly_limit | Max total spend per calendar month |
allowed_contracts | Whitelist of contract addresses the signer can interact with |
allowed_functions | Whitelist of function selectors (e.g. only transfer, approve) |
blocked_addresses | Blacklist — block sends to known bad actors or honeypots |
rate_limit | Max number of transactions in a time window |
time_window | Only allow signing during specific hours (e.g. business hours UTC) |
Built-in policies and rules engine policies are evaluated together. Every active constraint must pass before the server co-signs. Stack them to build defense in depth.
User Share (Browser Signing)
| Method | Path | Purpose |
|---|
POST | /signers/:id/user-share | Store wallet-encrypted user share blob |
GET | /signers/:id/user-share | Retrieve encrypted user share blob |
User+Server Signing (Dashboard Override)
| Method | Path | Purpose |
|---|
POST | /signers/:id/sign/session | Start User+Server signing session |
POST | /signers/:id/sign/round | Exchange CGGMP24 protocol messages |
POST | /signers/:id/sign/complete | Finalize User+Server signing |
User+Server signing runs CGGMP24 in the browser via WASM. The user share is decrypted client-side with the wallet signature. The server only sees protocol messages — never the raw share.
DKG (Distributed Key Generation)
| Method | Path | Purpose |
|---|
POST | /dkg/init | Start DKG ceremony |
POST | /dkg/finalize | Complete DKG, distribute shares |
Audit Log
| Method | Path | Purpose |
|---|
GET | /audit-log | Paginated audit log (all signing requests) |
GET | /audit-log/export | Export audit log as CSV |
Auth Endpoints
| Method | Path | Purpose |
|---|
POST | /auth/register | Register new wallet user |
POST | /auth/verify-email | Verify email address |
POST | /auth/passkey/register | Register a passkey (WebAuthn) |
POST | /auth/passkey/login-challenge | Get passkey login challenge |
POST | /auth/passkey/login | Authenticate with passkey, receive JWT |
POST | /auth/logout | Invalidate session |
GET | /auth/me | Get current authenticated user |
Networks and Contracts
| Method | Path | Purpose |
|---|
GET | /networks | List all enabled networks |
GET | /contracts | List known contracts (supports ?chainId= filter) |
POST | /contracts | Add a known contract |
DELETE | /contracts/:id | Remove a known contract |
System
| Method | Path | Purpose |
|---|
GET | /health (no /api/v1 prefix) | Health check. Returns 200 when healthy, 503 when degraded. |
Error Responses
All errors follow a consistent format:
{
"statusCode": 403,
"message": "Policy violation",
"violations": [
{
"policyId": "uuid",
"type": "spending_limit",
"message": "Transaction exceeds spending limit of 1.0 ETH"
}
]
}
| Status | Meaning |
|---|
400 | Bad request — invalid input |
401 | Unauthorized — missing or invalid auth |
403 | Forbidden — policy violation or signer paused |
404 | Not found |
503 | Service degraded — Vault sealed or DB unreachable |
Policy violations return 403 with a violations array. Every violation includes the policy type and a human-readable message. All violations are logged to the audit trail.
Next Steps
