agentic-terminal

---
name: agentic-terminal
description: Discover OP-verified merchants accepting Lightning, BOLT12, L402, or USDT, and complete payment handoff. Use when an agent needs to find a merchant on Bitcoin/Tether rails or check a merchant's payment endpoint before transacting.
---

# 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:

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

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

```bash
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:

```bash
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

```js
// 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"`.