Agentic API

Overview

The Agentic API is designed for autonomous AI agents that need to access Atlas Graph services without human intervention. Using the x402 protocol, agents can pay for API calls directly with their wallet - no signup, no API keys, no subscriptions.

How it works

1. 1 Agent sends a request to any Agentic API endpoint
2. 2 Server responds with HTTP 402 and payment details
3. 3 Agent signs a USDC permit for the specified amount
4. 4 Agent resends request with payment signature in headers
5. 5 Server verifies payment and returns the data

Available Endpoints

Response Format

All Agentic API responses follow a consistent structure with metadata for logging and debugging.

Success Response Structure

Every successful response includes a meta object and a data object:

{
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_ms": 245,
    "processed_at": "2026-03-11T12:00:00Z",
    "payment": {
      "paid": true,
      "method": "x402",
      "amount_usdc": "0.01",
      "amount_atomic": 10000,
      "tx_hash": "0xabc123...",
      "payer": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
      "network": "eip155:8453"
    },
    "endpoint": "/api/v1/agentic/risk/{address}",
    "chain_id": 1
  },
  "data": {
    "address": "0x1f98431c8ad98523631ae4a59f267346ea31f984",
    "chain_id": 1,
    "risk_score": 40,
    "risk_level": "MEDIUM",
    "factors": [
      { "name": "pattern_detection", "score": 0.9 },
      { "name": "contract_age", "score": 0.5 }
    ],
    "erc8004_status": { "is_registered": false }
  }
}

Meta Fields

Why This Format?

• - Logging: AI agents can log full request/response traces with payment info
• - Cost Tracking: Agents can track spending per request automatically
• - Debugging: Use request_id to trace issues across systems
• - Performance: Monitor processing_ms for latency analysis

x402 Protocol

x402 is an HTTP-based payment protocol that enables machine-to-machine payments. It uses HTTP status code 402 (Payment Required) to signal that payment is needed.

402 Response Format

When you call an Agentic API endpoint without payment, you'll receive a 402 response:

HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Payment-Address: 0x1234...
X-Payment-Amount: 20000
X-Payment-Token: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

{
  "error": "payment_required",
  "message": "This endpoint requires payment",
  "payment": {
    "address": "0x1234...",
    "amount": "20000",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chain_id": 8453,
    "expires_at": "2026-03-11T12:05:00Z"
  }
}

Payment Token

All payments are made in USDC on Base network (Chain ID: 8453).

Payment Flow

The payment flow is designed to be simple and atomic - no pre-funding or escrow required.

Payment Headers

After signing the USDC permit, include these headers in your retry request:

// Retry request with payment headers
X-Payment-Signature: 0x...signed_permit...
X-Payment-Deadline: 1705752000
X-Payment-Nonce: 12345

Important Notes

• - Payment signatures are single-use (nonce-based)
• - Signatures expire after the deadline timestamp
• - Funds are only transferred after successful verification
• - Failed requests do not consume payment

Bazaar Discovery

The Bazaar endpoint allows AI agents to discover available services and their prices before making requests. This enables autonomous service discovery and cost estimation.

Response

{
  "version": "1.0",
  "provider": "Atlas Graph",
  "endpoints": [
    {
      "path": "/api/v1/agentic/simulate",
      "method": "POST",
      "price": { "amount": "10000", "token": "USDC", "chain_id": 8453 },
      "description": "TX Simulation with MEV analysis"
    },
    {
      "path": "/api/v1/agentic/risk/{address}",
      "method": "GET",
      "price": { "amount": "10000", "token": "USDC", "chain_id": 8453 },
      "description": "Risk Score with ERC-8004 check"
    },
    {
      "path": "/api/v1/agentic/defense/verify",
      "method": "POST",
      "price": { "amount": "5000", "token": "USDC", "chain_id": 8453 },
      "description": "ERC-8004 identity verification"
    },
    {
      "path": "/api/v1/agentic/metadata/fetch",
      "method": "POST",
      "price": { "amount": "5000", "token": "USDC", "chain_id": 8453 },
      "description": "AgentURI metadata retrieval"
    },
    {
      "path": "/api/v1/agentic/trace",
      "method": "POST",
      "price": { "amount": "5000", "token": "USDC", "chain_id": 8453 },
      "description": "Execution trace with failure analysis"
    }
  ],
  "payment_address": "0x...",
  "supported_tokens": ["USDC"],
  "supported_chains": [8453]
}

Use Cases

• - Budget estimation before executing tasks
• - Comparing prices across providers
• - Building autonomous agent workflows
• - Service health monitoring

ERC-8004 Identity

ERC-8004 is a standard for AI Agent Identity on Ethereum. It allows agents to register their identity on-chain, enabling trust and verification between agents.

What is ERC-8004?

• - On-chain registry for AI agent identities
• - Links agent address to metadata URI (AgentURI)
• - Enables agent-to-agent trust verification
• - Supports code hash and model fingerprint registration

Integration with Risk Score

The Risk Score API automatically checks ERC-8004 registration status. Registered agents receive a lower risk score, making them more trustworthy for other agents to interact with.

Registry Contract

My Agents

Register and monitor your ERC-8004 agents through the My Agents dashboard. Track on-chain activity, manage ownership claims, and view performance metrics.

Register & Claim

To add your agent to My Agents, you need to register and claim it. This links your ERC-8004 registered agent to your Atlas Graph account.

1. 1 Navigate to My Agents page
2. 2 Click "Register Agent" button
3. 3 Enter your agent's Chain ID and Agent ID
4. 4 System verifies you own the agent (wallet address matches)
5. 5 Agent is added to your dashboard

Dashboard Features

Ownership Verification

Only the owner of an ERC-8004 agent can claim it. The system verifies ownership by checking:

• - Your connected wallet address matches the agent's registered owner
• - The agent exists on the specified chain
• - The agent is not already claimed by another user

Unclaim Agent

You can remove an agent from your dashboard at any time by clicking the unclaim button. This does not affect the agent's on-chain registration - it only removes it from your Atlas Graph account.

Error Handling

Handle these error codes when integrating with the Agentic API.

Agent Examples TODO