API Reference

REST endpoints for managing agents, policies, permissions, and audit logs.

Base URL & Authentication

The management and validation API is available at

Base URL

https://api.projectaegis.ai

Every /api/v1 route except /auth/* requires authentication. Two methods are accepted:

API key

Send API keys with X-API-Key. Wallet-wide management keys belong only in a trusted setup process. An agent runtime should receive an expiring aegisrt_ key bound to that agent, account, and chain, with only the scopes it needs. The bundler:use scope reaches only the matching managed chain route and cannot perform wallet management.

X-API-Key: YOUR_API_KEY

JWT (dashboard / browser sessions)

Obtained by completing the SIWE handshake (/auth/nonce → /auth/verify), then sent as a bearer token.

Authorization: Bearer YOUR_JWT

Auth

Public endpoints — Sign-In with Ethereum

POST /api/v1/auth/nonceGet a nonce to sign for SIWE

POST /api/v1/auth/verifyVerify the signed message, return a JWT

auth-verify.json

// POST /api/v1/auth/verify
// Request
{
  "message": "app.projectaegis.ai wants you to sign in...",
  "signature": "0x..."
}

// Response
{
  "token": "eyJhbGciOi...",       // JWT — send as Authorization: Bearer
  "wallet_address": "0xYourWallet"
}

Agents

Create, deploy, and operate smart-account agents

POST /api/v1/agentsCreate an agent (smart account only)

GET /api/v1/agentsList your agents

GET /api/v1/agents/{id}Get one agent

PATCH /api/v1/agents/{id}Update an agent

DELETE /api/v1/agents/{id}Delete an agent

POST /api/v1/agents/syncSync on-chain agents into the dashboard

POST /api/v1/agents/{id}/register-onchainRegister the agent in IdentityRegistry

POST /api/v1/agents/{id}/deploy-smart-accountDeploy the ERC-4337 account (signer_type: wallet | generated)

GET /api/v1/agents/{id}/smart-accountGet smart-account info (address, signer, enforcer)

PUT /api/v1/agents/{id}/primary-permissionSelect the exact active, minted permission used by runtime handoffs

GET /api/v1/agents/{id}/doctor?permission_id=...Versioned account and permission readiness diagnostics

POST /api/v1/agents/{id}/x402/relayRelay a bot-signed authorizeX402Payment UserOp (gas-sponsored)

agents.json

// POST /api/v1/agents
// Request
{
  "name": "ETH Trader",
  "description": "Autonomous USDC<>WETH swapper"
}

// Response
{
  "id": "agent-uuid",
  "name": "ETH Trader",
  "wallet_type": "smart_account",
  "enforcement_level": "enforced",
  "status": "created"
}

Policies

Define what agents are allowed to do

POST /api/v1/policiesCreate a policy

GET /api/v1/policiesList policies

GET /api/v1/policies/{id}Get one policy

PUT /api/v1/policies/{id}Update draft metadata/rules; activated definitions require a replacement policy

DELETE /api/v1/policies/{id}Delete a draft policy

POST /api/v1/policies/{id}/activateActivate — writes it to PolicyRegistry on-chain

POST /api/v1/policies/{id}/revokeRevoke a policy

POST /api/v1/policies/{id}/reactivateReactivate a revoked policy

policies.json

// POST /api/v1/policies  — per-asset limits in each asset's OWN base units
// Request
{
  "name": "DeFi Trading Policy",
  "description": "Swaps and transfers with daily caps",
  "definition": {
    "actions": ["swap", "transfer"],
    "assets": { "protocols": ["*"], "chains": [8453] },
    "constraints": {
      "assetLimits": [
        { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "maxPerTx": "100000000", "maxDaily": "1000000000", "maxTxCount": 50 },
        { "asset": "native", "maxPerTx": "1000000000000000000",
          "maxDaily": "5000000000000000000" }
      ],
      "allowUnlistedAssets": false
    },
    "duration": {
      "validFrom": "2026-01-01T00:00:00Z",
      "validUntil": "2026-12-31T23:59:59Z"
    }
  }
}

// Response
{ "id": "policy-uuid", "status": "draft", "version": 1 }

Permissions

Bind an agent to a policy and enforce it on-chain

POST /api/v1/permissionsCreate a permission (agent + policy)

GET /api/v1/permissionsList permissions (filter by agent_id / policy_id)

GET /api/v1/permissions/{id}Get one permission

DELETE /api/v1/permissions/{id}Revoke / delete a permission

POST /api/v1/permissions/{id}/mintMint on-chain (grant + sync constraints to enforcer)

POST /api/v1/permissions/{id}/syncRe-sync on-chain state

permissions.json

// 1) POST /api/v1/permissions
{
  "agent_id": "agent-uuid",
  "policy_id": "policy-uuid",
  "valid_from": "2026-01-01T00:00:00Z",
  "valid_until": "2026-12-31T23:59:59Z"
}
// → { "id": "permission-uuid", "status": "created" }

// 2) POST /api/v1/permissions/{id}/mint
//    Registers PolicyRegistry.grantPermission + PermissionEnforcer.setConstraints
// → {
//     "id": "permission-uuid",
//     "onchain_token_id": "0xPermissionId",
//     "tx_hash": "0x...",
//     "status": "active"
//   }

Validation

Explain an exact call before signing. Policy and execution readiness are reported separately.

POST /api/v1/validate/explainExplain exact calldata with evidence and tri-state results

POST /api/v1/validateLegacy abstract policy check

POST /api/v1/validate/batchLegacy list of independent checks (not executeBatch)

POST /api/v1/validate/simulateSimulate without recording usage

Prefer POST /api/v1/validate/explain with the real target, value, and calldata. An allowed policy result does not prove funding, signer, bundler, or target success; an unknown result must not be promoted to ready. The legacy endpoint keeps onchain_enforced: true only to describe the account architecture and now labels its evidence boundary with evaluation_mode: "backend_abstract" and exact_onchain_check: false.

explain-action.json

// POST /api/v1/validate/explain
// Request
{
  "schemaVersion": "aegis.action-request.v1",
  "chainId": 8453,
  "account": "0x1111111111111111111111111111111111111111",
  "permissionId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "calls": [{
    "target": "0x2222222222222222222222222222222222222222",
    "value": "0",
    "data": "0xExactCalldata"
  }]
}

// Response (abbreviated)
{
  "schemaVersion": "aegis.action-explanation.v1",
  "correlationId": "...",
  "policyDecision": "unknown",       // allowed, denied, or unknown
  "executionReadiness": "unknown",   // ready, not_ready, or unknown
  "firstBindingCause": null,
  "checks": [],
  "discrepancies": []
}

Audit

Merged off-chain and on-chain activity trail

GET /api/v1/auditList audit logs (filter source=onchain|offchain)

GET /api/v1/audit/exportExport as JSON or CSV (incl. tx_hash / block_number)

POST /api/v1/audit/deniedReport a denied on-chain attempt so it surfaces in the trail

Experimental: Intent API

These endpoints are live but not end-to-end tested. The intent-envelope path is hidden from the UI and agent skill, and new accounts use MODE_POLICY_ONLY. Do not use these routes for production execution until Aegis explicitly marks them supported.

POST /api/v1/intentsExperimental — create an intent envelope

GET /api/v1/intentsExperimental — list intent envelopes

GET /api/v1/intents/{id}Experimental — read an intent

GET /api/v1/intents/{id}/payloadExperimental — read the payload

POST /api/v1/intents/{id}/executeExperimental — return execution metadata

API Keys & Webhooks

API Keys

POST /api/v1/api-keysCreate a management or bound, expiring runtime key

GET /api/v1/api-keysList API keys

DELETE /api/v1/api-keys/{id}Delete an API key

POST /api/v1/runtime/bundler/{chainID}Allowlisted JSON-RPC gateway to Aegis-managed Rundler

Webhooks

POST /api/v1/webhooksCreate a webhook

GET /api/v1/webhooksList webhooks

GET /api/v1/webhooks/{id}Get one webhook

PATCH /api/v1/webhooks/{id}Update a webhook

DELETE /api/v1/webhooks/{id}Delete a webhook