API x402

Envíe una carta desde código y pague en USDC

Las aplicaciones y los agentes de IA pueden enviar una carta a cualquier lugar de Australia y pagar por carta en USDC mediante x402. Sin cuenta, clave de API ni suscripción: solo un monedero y un cliente HTTP.

10 USDC por carta por correo ordinario20 USDC por carta por Express Post

Un solo precio hasta 20 páginas sin doblar, GST incluido. Se paga en USDC en Base, con el gas cubierto.

Inicio rápido Especificación OpenAPI

¿Por qué enviar cartas mediante x402?

La misma carta que en el sitio web, pagada por HTTP.

Sin cuenta ni clave de API No hay que registrarse. Su código crea una carta, obtiene un precio y paga con un pago en USDC firmado.
Un precio fijo por carta 20 USDC por Express Post, sin doblar en un sobre B4, o 10 USDC por correo ordinario, doblada para que quepa en el buzón, incluyen la impresión, el sobre, el franqueo y el seguimiento hasta 12 páginas dobladas o 20 sin doblar; después, 0.30 USDC por página. GST incluido, y el gas corre de nuestra cuenta.
La misma carta que en el sitio web Impresa tal como se sube en A4 de 80 g/m², con seguimiento, y enviada el mismo día hábil si se paga antes de las 14:30, hora de Melbourne.
Reembolsada si no puede enviarse Si no podemos enviarla, reembolsamos el importe íntegro, en USDC, al monedero que pagó. Una carta que cancelemos se reembolsa del mismo modo.

Para quién es

Agentes de IA Un agente que gestiona una disputa por una fianza, una reclamación a un seguro o una queja al ayuntamiento puede enviar la carta por sí mismo y pagar desde su propio monedero.
Aplicaciones y scripts Software de administración de fincas, jurídico y de facturación que envía cartas, sin cuenta de comerciante ni plan mensual.

Cinco solicitudes llevan una carta de su código al correo. No hay cuenta ni clave: el pago es todo lo que necesitamos.

send-letter.sh

# 1. Create the letter
curl -X POST https://unopost.com.au/api/x402 \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "notice.pdf",
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "service": "express",
  "signature": true
}'

# 2. Upload the document to the uploadUrl you got back
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @notice.pdf

# 3. Poll until the status is ready_to_send, and check the price
curl https://unopost.com.au/api/x402/$JOB_ID

# 4. Ask to send it: the 402 says what to pay
curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send

# 5. Sign the payment with an x402 client, and send it again
curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE"

Endpoints

Los endpoints son relativos a https://unopost.com.au. Las solicitudes y las respuestas son JSON; los errores son {"error": "..."}. Referencia completa: la especificación OpenAPI.

URL base

https://unopost.com.au

POST/api/x402Crea una carta. Gratis.PUTuploadUrlSube el documento al enlace firmado de la carta.GET/api/x402/{jobId}Obtiene el estado, el precio y el seguimiento de una carta.POST/api/x402/{jobId}/sendPague en USDC y la carta pasa a impresión.

Cree una carta

POST/api/x402

Haga POST con el nombre del archivo, la dirección del destinatario y su dirección de devolución. Recibe un jobId, una uploadUrl firmada y las URL para consultar y pagar la carta.

Cuerpo de la solicitud

fileNamestring · obligatorio: El nombre del archivo con su extensión: .pdf, .doc, .docx, .jpg, .jpeg o .png.
recipientAddress · obligatorio: La dirección a la que se envía la carta.
senderAddress · obligatorio: Su dirección de devolución, impresa en el sobre para que el correo que no pueda entregarse vuelva a usted.
servicestring · opcional: "express" para Express Post (el valor por defecto) o "regular" para correo ordinario.
duplexboolean · opcional: Imprime a doble cara. Por defecto, false. Las declaraciones juradas (statutory declarations) siempre van a una cara.
monoboolean · opcional: Imprime en blanco y negro. Por defecto, false: un documento que contiene color se imprime en color.
stapleboolean · opcional: Grapa las páginas una vez en la esquina superior izquierda. Solo para documentos de hasta 12 páginas; uno más largo se rechaza al calcular el precio. Por defecto, false.
foldboolean · opcional: Solo Express Post: dobla la carta en un sobre C5 en lugar de enviarla sin doblar en uno B4, sin costo adicional. Se ignora en documentos de más de 20 páginas, que van sin doblar. Las cartas por correo ordinario siempre van dobladas.
signatureboolean · opcional: Firma a la entrega, 6 USDC más, con cualquiera de los dos servicios. Con regular, la carta va por Correo certificado.

Dirección

El destinatario debe estar en Australia. La dirección de devolución puede estar en cualquier lugar: indique su país y el código postal pasa a ser opcional. Cada línea puede tener hasta 40 caracteres.

namestring · opcional: El nombre completo de la persona.
companystring · opcional: Una empresa u organización.
line1string · obligatorio: La dirección postal, o un PO Box como "PO Box 123".
line2string · opcional: Una segunda línea de dirección.
suburbstring · obligatorio: El barrio (suburb) o la localidad.
statestring · opcional: Omítalo en Australia: lo determina el código postal. Si se indica, uno de ACT, NSW, NT, QLD, SA, TAS, VIC o WA, en correspondencia con el código postal.
postcodestring · obligatorio: Cuatro dígitos.
countrystring · opcional: Solo para la dirección de devolución. Omítalo si es Australia.

Solicitud

curl -X POST https://unopost.com.au/api/x402 \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "notice.pdf",
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "service": "express",
  "signature": true
}'

Respuesta 200

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "uploadUrl": "https://unopost.com.au/uploads/019d7a7f-a183-752d-9b3b-11511179033b/notice.pdf?Expires=...&Signature=...&Key-Pair-Id=...",
  "statusUrl": "/api/x402/019d7a7f-a183-752d-9b3b-11511179033b",
  "sendUrl": "/api/x402/019d7a7f-a183-752d-9b3b-11511179033b/send",
  "status": "awaiting_upload"
}

Suba el documento

PUTuploadUrl

Haga PUT de los bytes del archivo sin procesar a uploadUrl en un plazo de 15 minutos. Hasta 50 MB y 80 páginas. La maquetación en A4 empieza en cuanto llega la subida; no hay que llamar a nada más.

Solicitud

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @notice.pdf

Consultar una carta

GET/api/x402/{jobId}

Espere el precio

Consulte cada pocos segundos hasta que status sea ready_to_send. La respuesta incluye entonces el número de páginas, el precio en payment, la sendUrl y una previewUrl con el PDF listo para imprimir, para revisarlo antes de pagar.

fold sigue ahora al servicio, true para correo ordinario y false para Express Post, y duplex puede ser false: las declaraciones juradas se imprimen a una cara. Una carta por correo ordinario de más de 12 páginas se rechaza al calcular su precio.

Siga la carta

Siga consultando, con menos frecuencia, hasta que la carta esté posted y, después, delivered. No hay correos electrónicos; cada novedad aparece en el estado.

Solicitud

curl https://unopost.com.au/api/x402/$JOB_ID

Respuesta 200 · ready_to_send

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "service": "express",
  "duplex": false,
  "mono": false,
  "fold": false,
  "signature": true,
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "pageCount": 3,
  "status": "ready_to_send",
  "previewUrl": "/preview/019d7a7f-a183-752d-9b3b-11511179033b/notice.pdf?Expires=...&Signature=...&Key-Pair-Id=...",
  "payment": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountAtomic": "20000000",
    "amountDisplay": "20 USDC",
    "payTo": "0x1111111111111111111111111111111111111111",
    "expiresAt": "2026-09-25T02:15:00Z"
  },
  "sendUrl": "/api/x402/019d7a7f-a183-752d-9b3b-11511179033b/send"
}

Respuesta 200 · posted

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "service": "express",
  "duplex": false,
  "mono": false,
  "fold": false,
  "signature": true,
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "pageCount": 3,
  "status": "posted",
  "providerReference": "LTR-8F3A21C9"
}

Pague y envíe

POST/api/x402/{jobId}/send

Haga POST a sendUrl sin pago. La respuesta es 402 Payment Required, con los requisitos de pago codificados en base64 en la cabecera PAYMENT-REQUIRED.

Firme el pago como describe el protocolo x402 (o deje que lo haga una biblioteca cliente de x402) y reenvíe la solicitud con la carga útil en una cabecera PAYMENT-SIGNATURE. Lo verificamos y lo liquidamos, y la carta pasa a impresión. La cabecera PAYMENT-RESPONSE contiene la liquidación.

¿Recibe un 409 con job not ready to send justo después de ready_to_send? Espere un momento y reintente. Si llama de nuevo después de pagar, se devuelve el estado sin cobrar dos veces.

Solicitud

curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send

Respuesta 402

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi...

{
  "error": "payment required"
}

Cabecera PAYMENT-REQUIRED, decodificada de base64

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "20000000",
      "payTo": "0x1111111111111111111111111111111111111111",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

Solicitud

curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE"

Respuesta 202

HTTP/2 202
payment-response: eyJzdWNjZXNzIjp0cnVlLC...

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "status": "sending"
}

Estados

awaiting_upload: A la espera del archivo.
processing: Maquetando el documento en A4 y calculando el precio.
ready_to_send: Con precio y a la espera del pago. El presupuesto dura 7 días.
sending: Pagada y en cola de impresión.
retrying: La impresión ha tenido un problema; lo reintentamos automáticamente.
posted: Impresa y depositada en Australia Post.
delivered: Entregada por Australia Post. El documento se eliminó en el momento del envío.
failed: No enviada; el motivo está en error, por ejemplo un presupuesto que caducó sin pagarse. Una carta pagada que no puede enviarse se reembolsa íntegramente.
refunded: El pago ha vuelto al monedero que lo realizó.

Errores

400: Solicitud no válida: por ejemplo, falta un campo, el tipo de archivo no es compatible, una línea de dirección supera los 40 caracteres, el código postal no corresponde al estado, firma a la entrega con correo ordinario, o una carta por correo ordinario de más de 12 páginas.
402: Se requiere el pago, o el pago no ha podido verificarse o liquidarse. error indica por qué.
404: No hay ninguna carta con ese jobId.
409: job not ready to send: espere a ready_to_send e inténtelo de nuevo. quote expired: cree la carta de nuevo.

Preguntas frecuentes

¿Qué es x402?

Un protocolo abierto para pagar por HTTP. El servidor responde 402 Payment Required con un precio; el cliente firma un pago en una stablecoin y reenvía la solicitud. Sin cuenta, tarjeta ni factura.

¿Qué necesito?

Un monedero en Base con suficiente USDC y un cliente HTTP. No hace falta ETH para el gas: el pago es una autorización firmada de transferencia de USDC, y nosotros cubrimos la comisión de red.

¿Cuánto cuesta una carta?

20 USDC por Express Post hasta 20 páginas y, después, 0.30 USDC por página, o 10 USDC por correo ordinario para una carta de hasta 12 páginas, GST incluido. La firma a la entrega cuesta 6 USDC más con cualquiera de los dos servicios; el correo ordinario con firma es el Correo certificado, 16 USDC. El seguimiento, la impresión a doble cara y en blanco y negro, el grapado de hasta 12 páginas y doblar una carta de Express Post en un sobre DL con ventana son gratis. La respuesta de estado muestra el precio exacto antes de pagar.

¿Puedo revisar la carta antes de pagar?

Sí. Cuando está lista para enviarse, previewUrl es el PDF listo para imprimir, maquetado en A4 exactamente como se imprimirá. No se cobra nada hasta que usted paga.

¿Cuándo se envía y cuánto tarda en llegar?

Las cartas pagadas antes de las 14:30, hora de Melbourne, de un día hábil se envían ese día; las posteriores, el siguiente día hábil. Express Post suele llegar el siguiente día hábil dentro de la red de Express Post; el correo ordinario, en 3 a 7 días hábiles.

¿Qué ocurre si la carta no puede enviarse?

Su estado pasa a failed y reembolsamos el importe íntegro en USDC al monedero que pagó, tanto si falló como si la cancelamos nosotros. Para cualquier otra cosa, escriba a support@unopost.com.au con el jobId.

¿Qué pasa con mi documento?

Se cifra en tránsito y se elimina de forma permanente, junto con su copia lista para imprimir, una vez depositada la carta en Australia Post. Si una carta no se paga o no puede enviarse, se elimina a los 14 días.

¿Adónde pueden ir las cartas?

A cualquier dirección de Australia, incluidos los PO Boxes, en todos los estados y territorios. La API no envía al extranjero.

¿Quién es responsable de lo que envía un agente?

Usted. Toda carta pagada desde su monedero es suya, incluida la que un agente haya escrito y enviado siguiendo sus instrucciones, y usted debe tener derecho a enviar lo que contiene. Nuestros términos enumeran lo que no puede ir por correo: suplantación de identidad, acoso, estafas, publicidad masiva no solicitada y todo lo que infrinja una orden judicial. Cancelamos las cartas que incumplen esas normas y las reembolsamos íntegramente. Si envía en nombre de otra persona, usted es responsable de su documento como si fuera suyo.

Precios

Concepto	Precio
Correo ordinario, doblada para que quepa en el buzón: hasta 12 páginas	10 USDC
Correo certificado, correo ordinario con firma a la entrega: hasta 12 páginas	16 USDC
Express Post, sin doblar en un sobre B4: 20 páginas incluidas; después, 0.30 USDC por cada página adicional	20 USDC
Express Post con firma a la entrega: 20 páginas incluidas; después, 0.30 USDC por cada página adicional	26 USDC
Seguimiento, impresión en color, a doble cara o en blanco y negro, y grapado	Gratis
Comisión de red (gas)	Cubierta

Los precios están en USDC en Base. El precio se fija una vez maquetado su documento en A4; los presupuestos duran 7 días.

Los precios pueden cambiar. El uso de este servicio está sujeto a nuestros Términos del servicio y a nuestra Política de privacidad.