# PostBridge AI Agent Quickstart

Use this page when a user asks an AI agent to send a physical letter.

## Canonical Endpoints

- Agent metadata: https://postbridge.ai/.well-known/agent.json
- DID document: https://postbridge.ai/.well-known/did.json
- Agent metadata schema: https://postbridge.ai/schemas/agent-v1.json
- MCP endpoint: https://api.postbridge.ai/mcp
- REST API: https://api.postbridge.ai
- OpenAPI: https://api.postbridge.ai/openapi.json
- Static tool catalog: https://postbridge.ai/mcp-tools.json
- Developer docs: https://postbridge.ai/developers.html

## Safe Agent Flow

1. Collect the recipient address, sender address, country, service, and letter content.
2. Call `list_services` if the service code is unknown.
3. Call `quote_letter` or `negotiate_pricing` before any send action.
4. Show the user the recipient, sender, service, price, payment method, and delivery/proof level.
5. Ask for explicit user confirmation before calling `send_letter`.
6. After sending, return the `letter_id`, tracking status, and proof endpoint.

## Confirmation Required

`send_letter` creates a real physical mailing and may charge money. Do not call it unless the user has confirmed the final details.

Minimum confirmation text:

```text
Please confirm: send this letter from [sender] to [recipient] using [service] for [price/currency] via [payment method].
```

## Authentication

- Preferred for agents: x402 USDC on Base L2. The payment is the authorization.
- UCAN: use a DID and delegated capability token.
- API key: `Authorization: Bearer pb_live_...`, created through `POST /auth/register`.
- Compatibility alias: `POST /signup` maps to registration but `/auth/register` is canonical.

## Side Effects

- `list_services`, `quote_letter`, `negotiate_pricing`, `track_letter`, and `get_proof` are read-only or price-discovery operations.
- `accept_offer` creates an offer commitment record.
- `send_letter` prints, envelopes, posts, and bills for a physical letter.

## Supported Countries

- United States: `US`
- France: `FR`
- United Kingdom: `GB`
- Canada: `CA`
- Germany: `DE`

Postal service must match the recipient country, not the sender country.

## Data Handling

PostBridge handles mailing data only to quote, print, send, track, and prove delivery of letters. Uploaded PDFs are staged through single-use document URLs for order creation. See https://postbridge.ai/privacy.html.