# SendFax.sh -- Quickstart (agents)

Send a real fax in four steps. No account, no API key: you authorize each send
by paying for it with x402 or MPP (USDC).

Base URL: `https://sendfax.sh`

## 1. Submit the fax

`POST /api/v1/faxes` as `multipart/form-data`:

| Field      | Type            | Notes                                   |
|------------|-----------------|-----------------------------------------|
| `document` | file (PDF)      | The document to fax. Unencrypted, <=20 MB. |
| `to`       | string (E.164)  | Destination fax number, e.g. `+14155550123`. |

```bash
curl -sS https://sendfax.sh/api/v1/faxes \
  -F document=@invoice.pdf \
  -F to=+14155550123
```

## 2. Pay (HTTP 402)

The first call returns **HTTP 402 Payment Required**. The response advertises
the price ($0.05/page, USDC) two ways so any capable client can pay:

- **x402**: a JSON body with an `accepts` array of payment requirements, plus a
  `PAYMENT-REQUIRED` response header. Pay, then retry the exact same request
  with an `X-PAYMENT` header carrying the payment payload.
- **MPP** (Machine Payment Protocol, mpp.dev): a `WWW-Authenticate: Payment`
  response header describing the same charge. Pay, then retry with the
  `PAYMENT` header your MPP client produces.

```
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment
PAYMENT-REQUIRED: <base64 payment requirements>
Content-Type: application/json

{
  "x402Version": 1,
  "error": "payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "USDC",
      "maxAmountRequired": "50000",
      "resource": "https://sendfax.sh/api/v1/faxes",
      "description": "Fax transmission -- $0.05/page",
      "mimeType": "application/json"
    }
  ]
}
```

`maxAmountRequired` is in USDC base units (6 decimals): `50000` = $0.05 for a
one-page fax; multiply by the page count for longer documents.

## 3. Retry with payment -> accepted

On success you get **HTTP 202 Accepted**:

```json
{ "id": "fax_9f3c2a...", "statusUrl": "https://sendfax.sh/f/fax_9f3c2a..." }
```

## 4. Poll status (free)

`GET /api/v1/faxes/{id}` -- no payment required. Poll until a terminal status:

```json
{
  "id": "fax_9f3c2a...",
  "status": "delivered",
  "pageCount": 1,
  "toMasked": "**** 0123",
  "failureReason": null,
  "createdAt": 1752096000000,
  "terminalAt": 1752096010000
}
```

Status progression: `queued -> media_processed -> sending -> delivered`, or
`failed` (see `failureReason`). Terminal statuses are `delivered`, `failed`,
and `expired`.

## Notes

- **Privacy**: real-time fax. The PDF is streamed to Telnyx and deleted after
  sending -- never stored by us. The destination number is redacted to its last
  4 digits (`toMasked`) once the job reaches a terminal state.
- **Errors** use `application/problem+json` (RFC 9457): `{ type, title, status,
  detail }`.
- **Test mode**: no real fax line is provisioned yet, so the pipeline simulates
  the `queued -> ... -> delivered` transitions on a timer. The full flow is
  demonstrable end to end.