# AGENTS.md — Conduit

Guidance for AI agents that transact through Conduit via MCP.

## Production MCP (live)

```
POST/GET  https://mcp.aiconduit.app/mcp
```

Connect any MCP client:

```json
{
  "mcpServers": {
    "Conduit Agentic Commerce": {
      "url": "https://mcp.aiconduit.app/mcp"
    }
  }
}
```

Install hub: https://aiconduit.app/connect
UCP profile: https://aiconduit.app/.well-known/ucp
Capability manifest: https://aiconduit.app/.well-known/agent.json

### Codex (recommended among OpenAI clients)

Codex CLI / IDE / ChatGPT desktop Codex host can run the **full** Conduit loop (MCP + Skill): autonomous `payable_now`, AP2 mandates, and x402 — same as Cursor or Claude Code.

```bash
codex mcp add conduit --url https://mcp.aiconduit.app/mcp
mkdir -p ~/.agents/skills/conduit && \
  curl -fsSL https://aiconduit.app/skills/conduit/SKILL.md \
    -o ~/.agents/skills/conduit/SKILL.md
codex mcp list
```

Manual config (`~/.codex/config.toml`):

```toml
[mcp_servers.conduit]
url = "https://mcp.aiconduit.app/mcp"
```

ChatGPT web Apps are **limited** for Conduit: public Apps require external checkout and cannot use crypto rails. Prefer Codex (or Cursor / Claude Code) for checkout; ChatGPT Developer mode MCP is discovery/handoff only.

### Local development

```
POST/GET  http://localhost:4000/mcp
```

## Tools

| Tool | Purpose |
| --- | --- |
| `create_agent_profile` | Register an agent (public key + payment rails + default destination). Returns `agent_id` + `persist` guide. **Check ~/.conduit/credentials.json first — do not recreate if it exists.** |
| `authenticate_agent` | Re-authenticate by signing a server challenge. Load `agent_id` + `private_key` from ~/.conduit/credentials.json. Two-step: call without `nonce` to get a challenge, sign it, call again with `nonce` + `signature`. No filesystem? Give the human a terminal command to read/sign — never paste private_key into chat. |
| `update_agent_profile` | Patch handle, payment rails, default destination (include **postcode**), business profile, or preferences. Prefer after signup before search. |
| `payment_methods` | List or enable agent payment methods (`action`: `list` \| `enable`). |
| `request_payment_mandate` | Create an AP2 spend mandate; returns `approval_url` (tokenized) for human approval. Required for **autonomous** checkout on mandate-gated merchants. |
| `manage_mandate` | List, update, or revoke AP2 mandates (`action`: `list` \| `update` \| `revoke`). Wider caps need human re-approval via `approval_url`. |
| `search_supply` | Multi-provider fan-out; AES-ranked offers with `badge` + `action`. **Always pass `agent_id`**. Returns `search_id`. Catalog `deliveryOptions` often empty. |
| `get_supply_details` | Full normalized product detail. Pass `search_id` + `agent_id` (refreshes badge/action). |
| `get_delivery_estimate` | Non-committing checkout probe for shipping ETA/cost. Prefer over `execute_order` when comparing delivery. |
| `execute_order` | Handoff or autonomous completion. Handoff returns `billBreakdown` (shipping). Use `idempotency_key`. |
| `list_orders` | List orders for an agent (`{ orders }`). Optional `status` (CANCELLED→ABANDONED) or `open_only` for in-flight. |
| `track_order` | Honest deal-type-aware status (never fabricates carrier scans). |
| `get_order_events` | Lifecycle timeline — transitions only. |
| `update_order_status` | Agent correction or degraded-handoff recovery. Owning `agent_id` required. |
| `get_dispute_path` | Refund/chargeback/report paths. |
| `submit_feedback` | Report delivery/quality; updates reputation. |

Tool list: create_agent_profile, authenticate_agent, update_agent_profile, payment_methods, request_payment_mandate, manage_mandate, search_supply, get_supply_details, get_delivery_estimate, execute_order, list_orders, track_order, get_order_events, update_order_status, get_dispute_path, submit_feedback

## Identity & payment model

- Agent holds a **keypair**; Conduit stores only the public key.
- Conduit is orchestrator only — never holds funds. Merchant is merchant-of-record.
- Badge `handoff` → open `continue_url`. Badge `payable_now` → autonomous with active AP2 mandate.

## Identity persistence

- Path: `~/.conduit/credentials.json` (expand `~` to `$HOME` / `%USERPROFILE%`). Override: env `CONDUIT_CREDENTIALS_PATH`.
- Required: `version`, `agent_id`, `public_key`, `private_key` (never send private key to Conduit). One active profile per path.
- Bootstrap: read file first → reuse if present; after `create_agent_profile`, write file immediately → `update_agent_profile` with `default_destination` + **postcode** → then search.
- No filesystem? Fallback only — prefer loading private_key from disk when you can. Else: (1) `jq -r .agent_id ~/.conduit/credentials.json` (2) `authenticate_agent(agent_id)` → forward `terminal` verbatim (Node crypto ES256; never prints private_key) (3) paste `{agent_id,nonce,signature}` back. Never invent a script that encodes the key. Never paste `private_key` into chat.

## Delivery

Catalog `deliveryOptions` are often empty. Call `get_delivery_estimate(supply_id, agent_id)` for authoritative `etaText` / `options` / `shippingCost` (non-committing checkout). Prefer that over `execute_order` when only comparing delivery.

## Hints

Every outcome includes `hint` and optional `next: { tool, args? }`. Structured errors: `{ error, hint, next? }`.

## Correlation

Carry `search_id` from `search_supply` through details, execute, feedback. Use `idempotency_key` on every `execute_order`.

## Typical sequences

**Handoff:** create_agent_profile → write ~/.conduit/credentials.json → update_agent_profile(default_destination with postcode) → payment_methods(list) → search_supply(agent_id) → get_supply_details(agent_id, search_id) → get_delivery_estimate(agent_id) → execute_order → open continue_url → track_order → submit_feedback

**Autonomous:** create_agent_profile → write credentials → update_agent_profile(postcode) → request_payment_mandate → human opens approval_url → search_supply → badge=payable_now → execute_order → track_order → submit_feedback

**Returning session:** read ~/.conduit/credentials.json → authenticate_agent (optional) → search_supply(agent_id) …

**Degraded handoff:** execute_order (handoffQuality=degraded) → complete continue_url → update_order_status(agent_id, ..., external_checkout_id, handoff_endpoint) → track_order

List tools return envelopes (`{ methods }`, `{ mandates }`, `{ events }`, `{ orders }`). Mandate starts as `PENDING_HUMAN_APPROVAL` — open `approval_url` as returned (includes approve token). Wrong-agent revoke/status → `mandate_forbidden` / `order_forbidden`.

## Offer badges

Use **badge** / **action** (and **recommended**) to decide — not merchant autonomy.

| Badge | Action | Meaning |
| --- | --- | --- |
| `payable_now` | `execute_autonomous` | Autonomous checkout available |
| `needs_mandate` | `request_mandate` | Call request_payment_mandate first |
| `handoff` | `execute_handoff` | Complete on merchant continue_url (any card OK there) |
| `enable_rail_to_buy` | `enable_rail` | Call payment_methods(enable) first |
| `coming_soon` | `skip` | Rail not live for agent checkout |
| `discovery_only` | `skip` | Browse only |

**Any card** (`bank_card`): handoff-only for now — human pays with any card on the merchant site. Agent card vault is not live; do not enable.

## Rate limits

- ~300 MCP requests/min per IP (burst 100) — designed for parallel subagents
- ~120 REST /api requests/min per IP
- ~60 `search_supply` + ~180 tool calls/min per `agent_id` (anonymous search is IP-capped)
- Exact `/health` exempt; `/health/ucp-signer` rate-limited; HTTP 429 + Retry-After on Nest agent limits

Contact: conduit@asmodeoux.me · https://telegram.me/asmodeoux