x402 Fax API

Overview

The API is organised around a single resource, the fax job. It uses JSON request and response bodies and standard HTTP status codes. Every request is unauthenticated except the one that sends the fax, which carries a signed x402 payment.

A complete send takes four steps:

1. Create a job with the destination number and file name.
2. Upload the document to the pre-signed URL you get back.
3. Poll the job until it is ready_to_send, then read the quoted price.
4. Pay and send: take the 402 challenge, sign it, retry.

Payments

Payment happens on the send endpoint using the standard x402 handshake:

1. Call the endpoint without payment. It responds 402 Payment Required with a base64-encoded JSON challenge in the PAYMENT-REQUIRED header.
2. Sign one of the entries in accepts with an x402 client and your wallet.
3. Repeat the identical request with the base64 payload in a PAYMENT-SIGNATURE header.

Settlement is on Base (eip155:8453) in USDC. The quote in the job's payment object is valid until expiresAt. The send endpoint is idempotent: replaying a paid request never charges twice, and the settlement receipt comes back in the PAYMENT-RESPONSE header.

Errors

Codes in the 2xx range mean success. 402 is an expected step in the payment flow, not a failure. Other 4xx codes mean the request can't be fulfilled as sent. Error bodies have a single human-readable error field.

Job statuses

The job object

The shape varies by status: fields appear as the job progresses.

Attributes

• jobIdstring
  Unique identifier for the job.
• faxNumberstring
  Destination fax number in E.164 format.
• statusenum
  Where the job is in its lifecycle. See Job statuses.
• pageCountinteger
  Number of fax pages after conversion, excluding the cover sheet. Present once the document has been processed.
• previewUrlstring
  Relative URL of a PDF preview of what will be transmitted, when available.
• scheduleobject
  Present when the job was created with scheduledTime.
  Show child parameters
• paymentobject
  Only when status is ready_to_send. The exact amount and destination for the x402 payment.
  Show child parameters
• sendUrlstring
  Only when status is ready_to_send. Relative URL to POST to for payment and sending.
• errorstring
  Only when status is failed. Failure message when available.

Create a fax job

Creates a job and returns a pre-signed uploadUrl. Each job takes a single document; to fax several, merge them into one PDF first.

Parameters

• faxNumberstringRequired
  Destination fax number in E.164 format, e.g. +14155551212.
• fileNamestringRequired
  File name with extension. Used to infer the MIME type when mimeType is omitted.
• mimeTypestring
  Explicit MIME type, e.g. application/pdf.
• scheduledTimestring
  RFC 3339 timestamp. If omitted, the fax is sent as soon as payment settles.
• coverSheetobject
  Free cover page prepended to the fax. It does not count toward the page price.
  Show child parameters

Returns

The new job with status: "awaiting_upload", plus uploadUrl, statusUrl and sendUrl.

Upload the document

PUT the raw file bytes to the uploadUrl from the create call. Don't wrap them in JSON or multipart. Conversion starts as soon as the upload completes.

Accepted formats: PDF, Word, PNG, JPG, GIF, WebP, HEIC and TIFF, up to 100 MB.

Retrieve a job

Returns the current state of a job. Poll every 2 to 3 seconds after uploading until status is ready_to_send, then every 5 seconds after paying until it is sent or failed. Most faxes finish in 1 to 2 minutes per page.

Path parameters

• jobIdstringRequired
  The job ID returned by create.

Returns

A job object, or 404 if the ID is unknown or expired.

Pay and send

Pays for a ready_to_send job and queues it for transmission, or for its scheduledTime. See Payments for the handshake.

Path parameters

• jobIdstringRequired
  The job to send.

Headers

• PAYMENT-SIGNATUREstring
  Base64-encoded x402 payment payload. Omit it on the first call to receive the 402 challenge.

Returns

202 with status: "sending" once payment is accepted. Replaying the same paid request returns 202 while the fax is in flight and 200 with status: "sent" after delivery. 409 if the job isn't ready or the quote expired.

API descriptor

A compact, machine-readable summary of the endpoints and the expected call order. Point an agent here and it can work out the rest on its own.

OpenAPI spec

The full OpenAPI 3 document for this API, including every response shape. Use it to generate a client or to give an LLM agent the complete schema as a tool definition.

Open openapi.json