Agent Clear Documentation

Commerce infrastructure for AI agents. This guide covers authentication, service discovery, proxied API calls, provider registration, and SDK integration.

Quick Start

Get from zero to first API call in under 2 minutes.

1
Sign up and get your API key
Create an account at agentclear.dev/login. Go to Settings → API Keys → Create Key.
2
Discover services
Call POST /api/discover with a natural-language query describing what you need.
3
Make your first call
Call POST /api/proxy/{service_id} with your request body. Billing is automatic.

Your first discovery call

terminal

curl -X POST https://api.agentclear.dev/api/discover \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer axk_your_api_key_here" \
  -d '{
    "query": "convert PDF to structured JSON",
    "max_results": 5,
    "min_trust_tier": "verified"
  }'

You'll receive a ranked list of services matching your intent, sorted by a composite of relevance and trust score. Use the id field from the top result to make a proxied call.

Authentication

All API requests require a Bearer token in the Authorization header. API keys are created from your dashboard and follow the format:

axk_<32 hex characters>

Example: axk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Request headers

headers

Authorization: Bearer axk_your_api_key
Content-Type: application/json

Framework referral header

If you're an AI framework integrating Agent Clear, include the X-Framework-Ref header to attribute usage and earn the 40% revenue share on platform fees.

headers

X-Framework-Ref: framework_your_framework_id

Keep your API key secret

API keys are shown once at creation and cannot be retrieved again. Store them securely. If a key is compromised, revoke it immediately from Settings → API Keys.

Discovery API

POST/api/discover

Semantic search for services using natural language. The API generates an embedding of your query and performs a vector similarity search across all registered services. Results are ranked by a composite score combining relevance and trust tier.

Request body

Parameter	Type	Required	Description
query	string	required	Natural language description of the capability needed
max_results	number	optional	Maximum results to return (default 10, max 50)
min_trust_tier	string	optional	"basic" \| "verified" \| "premium"
protocol	string	optional	"openapi" \| "rest" \| "mcp" \| "graphql"
max_price_usd	number	optional	Maximum price per call in USD

Full example

terminal

curl -X POST https://api.agentclear.dev/api/discover \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer axk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -d '{
    "query": "extract tables from legal PDF documents",
    "max_results": 3,
    "min_trust_tier": "verified",
    "max_price_usd": 0.05
  }'

Response

response.json

{
  "results": [
    {
      "id": "svc_8f14e45f-ceea-467f-a83c-001a5b26e3b2",
      "name": "pdf-table-extractor",
      "display_name": "PDF Table Extractor Pro",
      "description": "Extracts tables from PDF documents with OCR support",
      "protocol": "rest",
      "price_per_call_usd": "0.003",
      "avg_latency_ms": 1200,
      "capability_tags": ["pdf", "table-extraction", "ocr"],
      "trust_tier": "verified",
      "trust_score": "0.85",
      "relevance_score": 0.94,
      "composite_score": 0.89,
      "provider_id": "usr_abc123",
      "rate_limit_rpm": 100
    }
  ],
  "bounty_logged": false,
  "query_embedding_tokens": 12
}

Bounty logging

When a query returns zero results, bounty_logged is true. The query is logged as an unfulfilled intent and appears on the Bounty Board.

Proxy API

POST/api/proxy/{service_id}

Execute a proxied call to a registered service. The proxy handles authentication with the upstream provider, billing (deducting from your wallet), latency measurement, and transaction logging. The request body is forwarded as-is to the upstream service.

Request

terminal

curl -X POST https://api.agentclear.dev/api/proxy/svc_8f14e45f-ceea-467f-a83c-001a5b26e3b2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer axk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -d '{
    "pdf_url": "https://example.com/contract.pdf",
    "pages": [1, 2, 3],
    "output_format": "json"
  }'

Response

response.json

{
  "upstream_status": 200,
  "latency_ms": 1340,
  "transaction_id": "txn_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "data": {
    "tables": [
      {
        "page": 1,
        "rows": [
          ["Party A", "Party B", "Effective Date"],
          ["Acme Corp", "Widget Inc", "2026-01-01"]
        ]
      }
    ],
    "page_count": 3
  }
}

Error codes

Status	Error	Description
401	unauthorized	Missing or invalid API key
402	insufficient_funds	Wallet balance too low for this call. Deposit more credits.
404	service_not_found	The service ID does not exist or has been deactivated
429	rate_limit_exceeded	You've exceeded the service's rate limit (RPM)
504	upstream_timeout	The upstream service did not respond within the timeout window

Service Registration

POST/api/services

Register a new service on the Agent Clear marketplace. Once registered, your service becomes discoverable via the Discovery API. An embedding is generated from your service description and capability tags for vector similarity search.

Registration payload

terminal

curl -X POST https://api.agentclear.dev/api/services \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer axk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -d '{
    "name": "pdf-table-extractor",
    "display_name": "PDF Table Extractor Pro",
    "description": "Extracts tables from PDF documents with high-accuracy OCR. Supports scanned documents, multi-page PDFs, and complex table layouts.",
    "version": "1.0.0",
    "endpoint_url": "https://your-api.com/v1/extract",
    "protocol": "rest",
    "price_per_call_usd": 0.003,
    "capability_tags": ["pdf", "table-extraction", "ocr", "document-parsing"],
    "rate_limit_rpm": 100,
    "input_schema": {
      "type": "object",
      "properties": {
        "pdf_url": { "type": "string", "description": "URL of the PDF to process" },
        "pages": { "type": "array", "items": { "type": "integer" } },
        "output_format": { "type": "string", "enum": ["json", "csv"] }
      },
      "required": ["pdf_url"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "tables": { "type": "array" },
        "page_count": { "type": "integer" }
      }
    }
  }'

Response

response.json

{
  "service_id": "svc_8f14e45f-ceea-467f-a83c-001a5b26e3b2",
  "name": "pdf-table-extractor",
  "display_name": "PDF Table Extractor Pro",
  "trust_tier": "basic",
  "trust_score": "0.50",
  "created_at": "2026-02-25T12:00:00Z"
}

Trust tier progression

New services start at Basic tier with a trust score of 0.50. Upgrade to Verified ($49/mo) for security scanning and a 1.1x discovery boost. Go Premium ($199/mo) for full code audit, signing, and 1.2x boost.

Webhooks

Agent Clear sends webhook events to notify your application about important events. Configure webhook endpoints from Settings → Webhooks in your dashboard.

Available events

Event	Description
service.called	A consumer made a proxied call to your service
service.registered	Your service was successfully registered
transaction.completed	A transaction was completed and funds settled
transaction.failed	A transaction failed (upstream error, timeout, etc.)
payout.completed	A payout to your bank account was completed
bounty.matched	A bounty was matched to your newly registered service
trust.upgraded	Your service trust tier was upgraded

Webhook payload example

webhook-payload.json

{
  "event": "service.called",
  "timestamp": "2026-02-25T12:34:56Z",
  "data": {
    "transaction_id": "txn_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "service_id": "svc_8f14e45f-ceea-467f-a83c-001a5b26e3b2",
    "consumer_id": "usr_xyz789",
    "amount": "0.003",
    "latency_ms": 1340,
    "status": "completed"
  }
}

Webhooks include an X-AgentClear-Signature header for payload verification. Validate using HMAC-SHA256 with your webhook secret.

SDK & Libraries

Official SDKs for Node.js and Python. Both SDKs provide typed interfaces for all API endpoints, plus the provider middleware for protecting your APIs.

JSNode.js

terminal

npm install @agentclear/sdk

Consumer usage

consumer.ts

import { AgentClear } from '@agentclear/sdk';

const ax = new AgentClear({ apiKey: 'axk_your_key' });

// Discover services
const { results } = await ax.discover({
  query: 'extract tables from legal PDF',
  maxResults: 5,
  minTrustTier: 'verified'
});

// Call the best match
const response = await ax.proxy(results[0].id, {
  pdf_url: 'https://example.com/contract.pdf',
  output_format: 'json'
});

console.log(response.data);

Provider middleware

provider.ts

import { requireAgentClear } from '@agentclear/sdk';
import express from 'express';

const app = express();

// Authenticate, bill, and log every incoming call
app.use(requireAgentClear({
  serviceId: 'svc_your_service_id',
  pricePerCall: 0.005
}));

// req.agentClear contains { consumerId, transactionId, ... }
app.post('/extract', async (req, res) => {
  const { pdf_url } = req.body;
  const tables = await extractTables(pdf_url);
  res.json({ tables, page_count: tables.length });
});

app.listen(3000);

PYPython

terminal

pip install agentclear

Consumer usage

consumer.py

from agentclear import AgentClear

ax = AgentClear(api_key="axk_your_key")

# Discover services
results = ax.discover(
    query="extract tables from legal PDF",
    max_results=5,
    min_trust_tier="verified"
)

# Call the best match
response = ax.proxy(
    service_id=results[0].id,
    body={"pdf_url": "https://example.com/contract.pdf"}
)

print(response.data)

Provider decorator (FastAPI)

provider.py

from fastapi import FastAPI
from agentclear.middleware import require_agent_clear

app = FastAPI()

@app.post("/extract")
@require_agent_clear(
    service_id="svc_your_service_id",
    price_per_call=0.005
)
async def extract_tables(request):
    pdf_url = request.body["pdf_url"]
    tables = await process_pdf(pdf_url)
    return {"tables": tables, "page_count": len(tables)}

Error Codes

All errors follow a standard JSON format. The request_id field can be provided to support for debugging.

error-response.json

{
  "error": "insufficient_funds",
  "message": "Your wallet balance is $0.002 but this call costs $0.003. Please deposit more credits.",
  "status": 402,
  "request_id": "req_abc123def456"
}

Complete error reference

Status	Error Code	Description
400	bad_request	Invalid request body or missing required fields
400	invalid_query	Discovery query is empty or exceeds 1000 characters
401	unauthorized	Missing, invalid, or expired API key
402	insufficient_funds	Wallet balance too low for this call
403	forbidden	API key does not have permission for this action
404	not_found	The requested resource does not exist
404	service_not_found	Service ID not found or deactivated
409	conflict	Resource already exists (e.g., duplicate service name)
422	validation_error	Request body failed schema validation
429	rate_limit_exceeded	Too many requests. Back off and retry with exponential backoff.
500	internal_error	Unexpected server error. Contact support with the request_id.
502	upstream_error	The upstream service returned an invalid response
504	upstream_timeout	The upstream service did not respond within 30 seconds

Need help?

Join the community or reach out to our developer support team.

GitHub Contact Support Discord