Skip to main content

​
Base URL

All API requests use this base URL: 
https://app.mandate.md/api

​
Authentication

The Mandate API uses two authentication schemes depending on the caller.

​
Agent authentication (RuntimeKeyAuth)

Agents authenticate with a runtime key in the Authorization header: 
Authorization: Bearer mndt_test_abc123...
Runtime keys use prefixes to enforce environment separation:
  • mndt_test_* for testnet (Sepolia, Base Sepolia)
  • mndt_live_* for mainnet (Ethereum, Base)
The runtime key is issued during agent registration and stored in ~/.mandate/credentials.json. You can regenerate it from the dashboard if compromised.

​
Dashboard authentication (Sanctum)

Dashboard users authenticate via GitHub OAuth. The Laravel session and Sanctum token are managed automatically by the frontend. Dashboard API endpoints require an active session or a Sanctum token.

​
Request format

All requests use JSON: 
Content-Type: application/json

​
Error format

Every error response returns JSON. The format depends on the error type. Policy block: 
{
  "allowed": false,
  "blockReason": "per_tx_limit_exceeded",
  "blockDetail": "$500.00 exceeds $100/tx limit",
  "declineMessage": "This transaction exceeds your per-transaction limit of $100."
}
General error: 
{
  "error": "Invalid or missing runtime key"
}
FieldPresent OnDescription
errorAll errorsHuman-readable error message
allowedValidation responsestrue if passed, false if blocked
blockReasonPolicy blocks (422), circuit breaker (403)Machine-readable reason code
blockDetailPolicy blocksSpecific detail about the violation
declineMessagePolicy blocksAdversarial counter-message for prompt injection defense
See Error Codes for the full HTTP status reference and Block Reasons for all blockReason values.

​
Endpoint groups

​
Agent API (7 endpoints)

These endpoints are called by agents using RuntimeKeyAuth.
MethodPathDescription
POST/agents/registerRegister a new agent (no auth required)
POST/activateSet the agent’s EVM address after registration
POST/validateAction-based validation (recommended)
POST/validate/rawRaw EVM validation with intent hash (deprecated)
POST/intents/{intentId}/eventsPost transaction hash after broadcast
GET/intents/{intentId}/statusPoll intent state
POST/risk/checkScreen an address against the risk database

​
Dashboard API (10+ endpoints)

These endpoints are called by the dashboard frontend using Sanctum authentication.
MethodPathDescription
POST/agents/claimLink an unclaimed agent to your account
POST/agents/createCreate a new agent directly
PUT/agents/{agentId}Update agent configuration
DELETE/agents/{agentId}Delete an agent
POST/agents/{agentId}/regenerate-keyIssue a new runtime key
GET/agents/{agentId}/policiesGet the agent’s current policy
POST/agents/{agentId}/policiesCreate or update the policy
POST/agents/{agentId}/circuit-breakToggle the circuit breaker
GET/approvalsList pending approvals
POST/approvals/{id}/decideApprove or reject a pending transaction

​
Open endpoint (1)

MethodPathDescription
POST/agents/registerNo authentication required. Returns runtimeKey, agentId, and claimUrl.

​
Rate limiting

The API enforces per-agent rate limits. See Rate Limits for default limits per endpoint category and retry strategies. Rate limit headers are included in every response:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • Retry-After (on 429 responses only)

​
Interactive playground

The API reference pages include an interactive playground powered by the OpenAPI specification. You can test endpoints directly from the docs using your runtime key. Enter your mndt_test_* key to test against the Mandate API without writing code.
Never use a mndt_live_* key in the playground. Use testnet keys for testing.

​
Next Steps

Register Agent

Create your first agent via the API.

Validate Transaction

Run a validation check against the policy engine.

Error Codes

Full HTTP status code reference.