§ 01 — Getting Started

What is Ambr

Ambr is the Agent Mandate & Binding Registry: the authorization and liability record for autonomous agents. An Agent Mandate records who authorized an agent, in what scope, under which law. Create, sign, and verify these dual-format Ricardian contracts through a single API -- no human bottleneck, no PDF workflows.

Get a Free Developer Key

Go to getamber.dev/activate, enter your email, and receive an API key instantly. The free developer tier includes 25 mandates per account, free forever, with no payment required.

Your First Mandate

Create a delegation mandate (template d1-general-auth) with a single POST request. Every request needs a template slug, a principal_declaration, and the template's required parameters:

curl -X POST https://getamber.dev/api/v1/contracts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "template": "d1-general-auth",
    "principal_declaration": {
      "agent_id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "principal_name": "Acme Corp",
      "principal_type": "company"
    },
    "parameters": {
      "principal_name": "Acme Corp",
      "principal_type": "corporation",
      "principal_registration_number": "DE-5589021",
      "principal_address": "1209 Orange St, Wilmington, DE 19801",
      "agent_id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "agent_type": "autonomous",
      "scope": "procurement and vendor payments",
      "categories": ["procurement", "api-calls"],
      "spending_limit_per_tx": 2500,
      "spending_limit_monthly": 10000,
      "duration_months": 12,
      "governing_law": "Delaware"
    }
  }'

The response returns the mandate's contract_id, a SHA-256 content hash, a reader URL for the counterparty, and a sign URL for wallet-based execution. Call GET /api/v1/templates for each template's full parameter list.

§ 02 — Contract Lifecycle

Create

POST /api/v1/contracts creates a new Agent Mandate (a dual-format Ricardian contract) from a template. The response includes the mandate's ID, a SHA-256 content hash, a reader URL (with embedded share token), a sign URL, and a handshake URL.

{
  "contract_id": "amb-2026-0042",
  "sha256_hash": "9f86d081884c...",
  "status": "draft",
  "reader_url": "https://getamber.dev/reader/9f86d081884c...?token=...",
  "sign_url": "https://getamber.dev/api/v1/contracts/amb-2026-0042/sign",
  "handshake_url": "https://getamber.dev/api/v1/contracts/amb-2026-0042/handshake",
  "next_step": "Contract created as draft. Both parties sign (ECDSA) to activate."
}

Share

Send the reader_url to the counterparty. The URL contains a share token that grants read access to the mandate without requiring an API key. The counterparty can review the full terms before proceeding to handshake or signature.

Handshake

POST /api/v1/contracts/:id/handshake lets the counterparty accept, reject, or request changes to a mandate. The handshake also records a visibility preference (private, metadata-only, public, or encrypted).

{
  "action": "accept",        // "accept" | "reject" | "request_changes"
  "visibility": "private",   // "private" | "metadata_only" | "public" | "encrypted"
  "wallet_address": "0x..."
}

Sign

POST /api/v1/contracts/:id/sign submits an ECDSA wallet signature. Bilateral mandates require two signatures: the first moves the mandate to pending status, the second activates it and triggers on-chain minting. One-sided mandates (P2 Power of Attorney) activate on the principal's single signature.

Verify

GET /api/v1/contracts/:id returns the full mandate including its SHA-256 hash. Compare this hash against the on-chain record to verify the mandate has not been tampered with since signing.

§ 03 — Agent Integration

A2A Discovery

AI agents discover Ambr through the standard A2A well-known endpoint:

GET https://getamber.dev/.well-known/agent.json

The agent card describes available capabilities, authentication methods, and supported interaction protocols.

MCP Server

Add Ambr as an MCP server in your agent configuration:

{
  "mcpServers": {
    "ambr": {
      "url": "https://getamber.dev/api/mcp",
      "headers": { "X-API-Key": "YOUR_KEY" }
    }
  }
}

The MCP server exposes six tools -- ambr_list_templates, ambr_create_contract, ambr_get_contract, ambr_get_contract_status, ambr_verify_hash, and ambr_agent_handshake -- so any MCP-compatible agent can manage mandates natively. Contract creation accepts an API key or x402 pay-per-call.

REST API

All endpoints accept and return JSON. Authenticate with the X-API-Key header or a share token where noted. Base URL: https://getamber.dev/api/v1

x402 Pay-per-mandate

Instead of an API key, agents can pay per mandate using the x402 protocol. Include a payment header with each request. The server validates the payment proof on-chain before processing the mandate creation. This enables fully autonomous agent-to-agent commerce without pre-registration.

§ 04 — API Reference

Endpoints

Copy-paste request examples for every endpoint — including error codes and rate limits — live on the developers page.

§ 05 — Wallet & Identity

Connect Wallet

The Ambr dashboard supports dual login: authenticate with your API key or connect a wallet directly. Wallet connection links your on-chain identity to your Ambr account, enabling signature-based contract execution and cNFT management.

Wallet Auth

The Reader Portal uses ECDSA signature verification for counterparty authentication. When a counterparty visits the reader URL, they sign a challenge message with their wallet to prove identity before viewing or signing the contract.

Contract NFTs

Each fully-signed contract is minted as an ERC-721 cNFT on Base L2. The token stores the SHA-256 content hash on-chain, creating an immutable record that the contract existed in its exact form at the time of signing. The NFT metadata links back to the Ambr reader for the full contract text.

Transfers

Contract NFTs use counterparty-gated transfers. Both signing parties must approve a transfer before the NFT can move to a new wallet. This prevents unilateral reassignment of contractual obligations.

§ 06 — Payment Methods

Pricing

x402 Pay-per-Mandate (Agent-Native)

No account needed. Agents pay per mandate directly with crypto on Base L2. Include the transaction hash in the X-Payment header. Live rates for the full catalog: GET /api/v1/pricing.

Monthly Subscriptions (Predictable Billing)

For teams that prefer a monthly plan with included mandates and unlimited AI drafting. Purchase via getamber.dev/activate (Stripe Checkout). The free Developer tier -- 25 mandates, no card -- is described above.

Credit Packs (One-Time)

Prefer to top up without a subscription? Buy a one-time credit pack -- credits are added to your key and do not expire.

Crypto

Pay for contracts with 7 tokens on Base L2:

Card Payments

Stripe Checkout handles card payments for the Personal and Business monthly subscriptions and for the Starter and Scale credit packs. Enterprise is a contact CTA. Use the free Developer tier or x402 crypto payments to get started without a card.

§ 07 — Trust Layer

ZK Identity

Demos Network

Ambr uses zero-knowledge proof identity verification via Groth16/BN128 zk-SNARKs powered by the DemosSDK. Counterparties prove attributes about themselves — jurisdiction, accreditation, age, or KYC status — without revealing the underlying data. The verifier receives a cryptographic proof, not raw personal information.

Proofs are verified server-side using the identity_with_merkle circuit. Each proof generates a unique nullifier that prevents replay attacks. Identity attestations are stored alongside the contract signature in the immutable record.

Enable ZK identity verification on any contract by setting require_zk_identity: true in the contract creation parameters. When enabled, signers must complete identity verification before their signature is accepted.

POST /api/v1/contracts
{
  "template": "d1-general-auth",
  "require_zk_identity": true,
  "parameters": { ... },
  "principal_declaration": { ... }
}