AT Directory

AT Directory is the agent commerce discovery surface for Bitcoin- and Tether-aligned payments. It indexes merchants that sell products, services, APIs, or content and accept Lightning, BOLT12, L402, or USDT (any chain), with trust attestations issued through Observer Protocol. It is not in the payment path — you discover merchants here and pay the merchant directly.

1. Connect — three paths, pick one

All three hit the same data and are anonymous + ungated (no credential to discover or transact).

A. Hosted MCP (recommended — lowest friction, no install). Point any MCP-compliant client at the hosted URL:

{ "mcpServers": { "at-directory": { "url": "https://mcp.agenticterminal.ai/mcp" } } }

B. Local MCP (npm). For air-gapped or offline-first setups:

npm install -g @agenticterminal/mcp-server   # Node >= 20
at-directory-mcp                              # stdio MCP server

C. Plain REST (no MCP client needed). For agent runtimes that don't speak MCP (OpenClaw, custom Lightning-native agents) — just HTTP:

curl 'https://mcp.agenticterminal.ai/v1/merchants?rail=lightning&category=gift-cards'
curl 'https://mcp.agenticterminal.ai/v1/merchants/bitrefill'
curl 'https://mcp.agenticterminal.ai/v1/categories'
curl 'https://mcp.agenticterminal.ai/v1/rails'
curl -X POST 'https://mcp.agenticterminal.ai/v1/merchants/bitrefill/verify?rail=lightning'

REST endpoints return the same JSON as the matching MCP tool (search_merchants ↔ GET /v1/merchants, get_merchant ↔ GET /v1/merchants/{id}, etc.), including the agent_identity field.

The MCP tool surface (paths A/B): search_merchants, get_merchant, verify_payment_endpoint, list_categories, list_rails, whoami.

2. Two orthogonal axes — always read both

Each merchant carries two independent signals. They do not imply each other.

OP trust tier (how verified the _merchant_ is):

• Tier 1 — self-attested; merchant claims the rails, unverified.
• Tier 2 — operator-verified; the AT operator transacted with the merchant and confirmed at least one claimed rail (v1.x: any OP-credentialed counterparty can attest, not just AT).
• Tier 3 — chain-anchored (ships v1.x; not present yet).

Agent-callable tier (how you _transact_):

• full-api — you complete the purchase end to end programmatically.
• structured-handoff — you pay autonomously from a structured request; fulfillment is human-handled.
• human-checkout — you discover the merchant but a human must complete a web checkout.

Worked examples:

• Tier 1 + full-api → you can buy now, but trust is self-asserted. Good for low-value, reversible buys.
• Tier 2 + human-checkout → endpoints verified, but you cannot complete autonomously; surface to a human.
• Tier 1 + human-checkout → discovery only; weakest combination for autonomous action.
• Tier 2 + full-api → strongest: verified and fully programmatic.

Reason about both before transacting. Never collapse them into a single "is this good" score.

3. Query patterns

// USDT-on-Tron gift-card merchants
search_merchants({ rail: 'usdt', chain: 'tron', category: 'gift-cards' });

// Fully agent-callable Lightning merchants, verified tier only
search_merchants({ rail: 'lightning', agent_callable_tier: 'full-api', trust_tier_min: 2 });

// Full record before transacting
get_merchant({ id: 'bitrefill' });

// Liveness check before committing to a handoff
verify_payment_endpoint({ merchant_id: 'bitrefill', rail: 'usdt' });

Every response echoes agent_identity. Reads are ungated: anonymous and credentialed callers see all tiers with the same limits — you do not need a credential to discover or transact. The field is honest signal you can branch on if you choose.

4. Payment handoff by rail

After get_merchant, the agent_endpoints object (when present) tells you how to transact:

• `mcp_server` — an MCP endpoint or npm: package for this merchant. Connect to it and use _its_ tools to complete the purchase. Example: Bitrefill exposes https://api.bitrefill.com/mcp.
• `rest_api` — base URL of a parallel REST surface, for agents that prefer REST over MCP. Same capability as mcp_server, different protocol; either is sufficient to transact. Convention: mcp_server and rest_api are _connection surfaces_; api_docs/openapi_url are _documentation_; auth_note is prose.
• `auth_note` — read this first. It states the credential the merchant requires, where to obtain it, and how to attach it. Example: "Requires Bitrefill API key (bitrefill.com/account/developers); embed as /mcp/<API_KEY>". Always check auth_note on every full-api merchant before connecting — different merchants authenticate differently.
• `api_docs` / `openapi_url` — human/machine docs for non-MCP integrations.

Rail mechanics for structured-handoff / human-checkout:

• Lightning — obtain the BOLT11 invoice at the merchant's checkout, pay it from your wallet.
• BOLT12 — feed the offer string into a BOLT12-aware wallet.
• L402 — present the WWW-Authenticate: L402 challenge to your payer, pay, retry with the token.
• USDT — take the deposit address + amount + memo, send from your wallet on the declared chain. Verify the address with verify_payment_endpoint first.

5. Credentials

Reads (search, get_merchant, verify) need no credential. Present an Observer Protocol DirectoryAccessCredential only to raise rate limits and to submit reviews/notes.

• Hosted: send the credential as the X-AT-Credential header (base64url-encoded JSON).
• Local: set AT_CREDENTIAL to the base64url-encoded credential JSON.

Confirm state any time with whoami() — it reports authenticated, tier_cap, and limits without running a real query.

6. When AT Directory is not enough

• Paid per-request API endpoints (L402-gated APIs): use 402index.io; the directory does not duplicate it.
• Physical-location-keyed merchant lookups: use BTC Map.
• x402-only merchants: out of scope by design.