AgentLayer API

Authentication

AgentLayer supports two authentication methods depending on your use case.

API Key (server-to-server)

For server-side integrations. Include your API key in every request header.

x-api-key: al_live_xxxxxxxxxxxxxxxxxxxxxxxx

Agent Token (autonomous agent)

For AI agents operating autonomously. Generate a token per agent from your dashboard.

x-agent-token: agt_live_xxxxxxxxxxxxxxxxxxxxxxxx

Errors

AgentLayer uses standard HTTP status codes. All errors return a JSON object with an error field.

Wallets

Each AI agent gets a delegated wallet with configurable spend limits. Limits reset automatically every day.

{
  "success": true,
  "wallet": {
    "agent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "agent_name": "Procurement Agent 01",
    "balance": 1000,
    "status": "active",
    "kya": {
      "did": "did:agentlayer:bd18c2df55727050e5fb3034c641ae50",
      "trust_level": "new",
      "trust_score": 0
    }
  }
}

curl .../api/wallets -H "x-api-key: al_live_xxx"

Payments

Execute a payment from an agent wallet. AgentLayer automatically enforces spend limits and returns a transaction ID.

{
  "success": true,
  "transaction": {
    "tx_id": "a1b2c3d4-...",
    "amount": 25,
    "description": "Market data purchase",
    "timestamp": "2026-05-24T12:00:00.000Z",
    "balance_after": 975
  }
}

{"error": "Dépasse la limite par transaction (max $100)"}

Recharge

Recharge an agent wallet via Stripe. The client deposits funds in USD and the wallet is credited automatically.

{"url": "https://checkout.stripe.com/pay/cs_test_..."}

KYA — Know Your Agent

Every agent has a cryptographic identity (DID) and a trust score that evolves based on transaction history.

{
  "agent_id": "f47ac10b-...",
  "agent_name": "Procurement Agent 01",
  "did": "did:agentlayer:bd18c2df55727050e5fb3034c641ae50",
  "trust_level": "verified",
  "trust_score": 30,
  "certificate_valid": { "valid": true, "expired": false },
  "stats": {
    "total_transactions": 15,
    "total_volume": 250,
    "average_transaction": 16.67
  },
  "spend_policy": {
    "max_per_transaction": 100,
    "max_daily": 500,
    "allowed_protocols": ["x402", "ap2", "mpp"]
  }
}

{
  "verified": true,
  "did": "did:agentlayer:bd18c2df...",
  "trust_level": "verified",
  "certificate_valid": true,
  "expired": false,
  "spend_policy": { "max_per_transaction": 100, "max_daily": 500 }
}

Multi-Agent Delegation

Agent A can delegate a budget to Agent B, which can delegate to Agent C. Each level has its own limits.

{
  "success": true,
  "child_wallet": { "agent_id": "...", "balance": 100 },
  "parent_balance_remaining": 900,
  "delegation_chain": [
    { "agent_name": "Agent A", "balance": 900, "is_delegated": false },
    { "agent_name": "Agent B", "balance": 100, "is_delegated": true }
  ]
}

curl .../api/delegate/AGENT_ID/chain -H "x-api-key: al_live_xxx"

Webhooks

Receive real-time HTTP notifications when events occur. All webhooks are signed with HMAC-SHA256.

Available Events

{
  "success": true,
  "webhook": {
    "webhook_id": "bbcf554e-...",
    "url": "https://your-server.com/webhook",
    "secret": "whsec_2f28f3cfcc6bc21916a986dcb8d4ef4efd958394dfa655bb",
    "events": ["payment", "blocked", "wallet_created", "topup"]
  }
}

Verify Signature (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-agentlayer-signature'];
  const valid = verifyWebhook(JSON.stringify(req.body), sig, 'whsec_xxx');
  if (!valid) return res.status(400).json({ error: 'Invalid signature' });
  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.json({ received: true });
});

x402 Protocol

AgentLayer implements the x402 payment protocol — any AI agent can pay for resources automatically over HTTP.

{
  "error": "Payment Required",
  "price": "$0.001",
  "network": "base-sepolia",
  "protocol": "x402",
  "accepts": [{ "scheme": "exact", "price": "$0.001", "network": "eip155:84532" }]
}

{
  "status": "success",
  "message": "Task executed via x402",
  "amount_paid": "$0.001 USDC"
}

Agent Integration

Once you've created a wallet and generated an agent token from your dashboard, your AI agent can pay autonomously using a single HTTP call — no browser, no session, no human required.

Step 1 — Create a wallet

From your dashboard, click "Créer un agent" and set spend limits. Copy the agent_id.

Step 2 — Generate an agent token

POST /client/tokens/create
{ "agent_id": "your-agent-id", "name": "Production Token" }

→ { "token": "agt_live_xxxxx" }

Step 3 — Pay from your agent

import requests

AGENT_TOKEN = "agt_live_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://agentlayer-production-98fa.up.railway.app"

def pay(amount, description):
    response = requests.post(
        f"{BASE_URL}/agent/pay",
        headers={
            "x-agent-token": AGENT_TOKEN,
            "Content-Type": "application/json"
        },
        json={"amount": amount, "description": description}
    )
    return response.json()

result = pay(10, "Market data purchase")
print(f"TX: {result['transaction']['tx_id']}")
print(f"Balance: ${result['agent']['balance_after']}")

const AGENT_TOKEN = "agt_live_xxxxxxxxxxxxxxxxxxxxxxxx";
const BASE_URL = "https://agentlayer-production-98fa.up.railway.app";

async function pay(amount, description) {
  const res = await fetch(`${BASE_URL}/agent/pay`, {
    method: "POST",
    headers: {
      "x-agent-token": AGENT_TOKEN,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ amount, description })
  });
  return res.json();
}

const result = await pay(10, "Market data purchase");
console.log(`TX: ${result.transaction.tx_id}`);
console.log(`Balance: $${result.agent.balance_after}`);

curl -X POST .../agent/pay \
  -H "x-agent-token: agt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "description": "Market data purchase"}'

Step 4 — Check balance

response = requests.get(
    f"{BASE_URL}/agent/balance",
    headers={"x-agent-token": AGENT_TOKEN}
)
balance = response.json()
print(f"Balance: ${balance['balance']}")
print(f"Spent today: ${balance['spent_today']} / ${balance['max_daily']}")
print(f"Trust level: {balance['trust_level']}")

Step 5 — Verify identity

response = requests.get(
    f"{BASE_URL}/agent/identity",
    headers={"x-agent-token": AGENT_TOKEN}
)
identity = response.json()
print(f"DID: {identity['did']}")
print(f"Trust: {identity['trust_level']} (score: {identity['trust_score']})")

Payment response format

{
  "success": true,
  "transaction": {
    "tx_id": "a2552304-5b04-49a1-9231-aa146f4d26b0",
    "amount": 10,
    "description": "Market data purchase",
    "timestamp": "2026-05-24T14:28:24.207Z",
    "balance_after": 990
  },
  "agent": {
    "agent_id": "107e9623-...",
    "agent_name": "My Agent",
    "balance_after": 990,
    "trust_level": "new"
  }
}

result = pay(500, "Large purchase")
if result.get("error"):
    print(f"Blocked: {result['error']}")
    # Handle: notify, retry later, request limit increase
elif result.get("success"):
    print(f"Paid! TX: {result['transaction']['tx_id']}")

Agent Tokens

Agent tokens authenticate individual AI agents. Each token is tied to a specific wallet and client account.

{
  "success": true,
  "token": "agt_live_38e683ca961443629e2981ff53aea562",
  "agent_id": "107e9623-...",
  "name": "Production Token"
}

x-agent-token: agt_live_xxx

curl .../agent/balance -H "x-agent-token: agt_live_xxx"

curl .../agent/identity -H "x-agent-token: agt_live_xxx"

Quickstart

Get an agent making payments in under 5 minutes.

1. Sign up and create a wallet

→ https://agentlayer-production-98fa.up.railway.app/signup.html
→ Create an agent with spend limits from the dashboard
→ Copy the agent_id

2. Generate an agent token

POST /client/tokens/create
{ "agent_id": "your-agent-id", "name": "My First Token" }
→ Copy the token: agt_live_xxx

3. Your agent pays autonomously

import requests

result = requests.post(
    "https://agentlayer-production-98fa.up.railway.app/agent/pay",
    headers={"x-agent-token": "agt_live_xxx"},
    json={"amount": 10, "description": "First autonomous payment"}
).json()

print(result["transaction"]["tx_id"])  # Done!

4. Set up webhooks

POST /client/webhooks
{ "url": "https://your-server.com/webhook", "events": ["payment", "blocked"] }
→ You're notified instantly on every event