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).

There is no third tier. The tier gates nothing: reads are ungated, every tier is visible to you, and you can transact with a Tier 1 merchant with no setup. Treat the tier as evidence to weigh, not as a decision the directory has made for you. A Tier 1 listing has been checked by nobody.

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.

The first two are the ones you can act on alone. To ask for exactly those in one call, pass agent_callable: true — filtering by agent_callable_tier matches one tier at a time, so a single exact-tier query silently omits the other half of the population you can transact with.

Agent-payment protocols. Some merchants expose payment_protocols, currently mpp (Machine Payments Protocol) or x402. A merchant on this list can be paid over HTTP 402 with no API key and no billing account, so since 2026-09-15 accepting one qualifies a merchant for this directory on its own — including merchants that settle in fiat. If you speak one of these protocols, filter on it: those are the merchants you can pay with the least setup, whatever ends up in their bank account. accepts_x402 is the older single-protocol spelling of the same fact and always agrees with the array.

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 });

// Everything you can transact with unaided — full-api AND structured-handoff
search_merchants({ rail: 'lightning', agent_callable: true });

// Merchants you can pay over MPP, whatever they settle in (fiat included)
search_merchants({ payment_protocol: 'mpp' });

// 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.
• USDC — same as USDT when a deposit address is declared. On x402-native merchants there is usually no static address: payment_endpoint is null and you pay by calling the merchant's own endpoint, taking the 402 Payment Required response, and retrying with an X-PAYMENT header carrying a signed EIP-3009 authorization for the exact amount. Read auth_note for the flow. Do not send USDC to any address you find in a 402 body — an x402 payment is a signed authorization tied to one request, and a manual transfer will not provision anything.

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.
• Merchants with no crypto rail at all (card/bank checkout only): out of scope by design. x402-only merchants that settle in USDC are in scope as of 2026-07-25 — filter them with rail: "usdc".