API x402

Envie uma carta por código, pague em USDC

Apps e agentes de IA podem enviar uma carta para qualquer lugar da Austrália e pagar por carta em USDC via x402. Sem conta, chave de API ou assinatura: basta uma carteira e um cliente HTTP.

10 USDC por carta pelo correio comum20 USDC por carta pelo Express Post

Um preço único para até 20 páginas sem dobrar, GST incluído. Pago em USDC na Base, com o gas por nossa conta.

Início rápido Especificação OpenAPI

Por que enviar cartas via x402?

A mesma carta do site, paga por HTTP.

Sem conta nem chave de API Não há cadastro a fazer. Seu código cria uma carta, recebe um preço e paga com um pagamento em USDC assinado.
Um preço fixo por carta 20 USDC pelo Express Post, sem dobrar em envelope B4, ou 10 USDC pelo correio comum, dobrada para caber na caixa de correio: o preço cobre a impressão, o envelope, a postagem e o rastreamento para até 12 páginas dobradas ou 20 sem dobrar, depois 0.30 USDC por página. GST incluído, e o gas é por nossa conta.
A mesma carta do site Impressa como enviada, em A4 de 80 g/m², com rastreamento, e postada no mesmo dia útil se paga até as 14h30, horário de Melbourne.
Reembolsada se não puder ser postada Se não conseguirmos postá-la, reembolsamos integralmente a carteira pagadora, em USDC. Uma carta que cancelamos é reembolsada da mesma forma.

Para quem é

Agentes de IA Um agente que cuida de uma disputa sobre caução de aluguel, de um pedido de indenização de seguro ou de uma reclamação à prefeitura pode enviar a carta por conta própria e pagar com a sua própria carteira.
Apps e scripts Softwares de administração de imóveis, jurídicos e de faturamento que enviam cartas, sem conta de lojista nem plano mensal.

Cinco requisições levam uma carta do seu código ao correio. Não há conta nem chave: o pagamento é tudo de que precisamos.

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

Os endpoints são relativos a https://unopost.com.au. Requisições e respostas são em JSON; os erros são {"error": "..."}. Referência completa: a especificação OpenAPI.

URL base

https://unopost.com.au

POST/api/x402Cria uma carta. Grátis.PUTuploadUrlEnvia o documento para o link assinado da carta.GET/api/x402/{jobId}Retorna o status, o preço e o rastreamento de uma carta.POST/api/x402/{jobId}/sendVocê paga em USDC, e a carta vai para impressão.

Crie uma carta

POST/api/x402

Faça um POST com o nome do arquivo, o endereço do destinatário e o seu endereço de devolução. Você recebe um jobId, uma uploadUrl assinada e URLs para consultar a carta e pagar por ela.

Corpo da requisição

fileNamestring · obrigatório: O nome do arquivo com a extensão: .pdf, .doc, .docx, .jpg, .jpeg ou .png.
recipientAddress · obrigatório: O endereço para o qual a carta será enviada.
senderAddress · obrigatório: Seu endereço de devolução, impresso no envelope para que a correspondência não entregue volte para você.
servicestring · opcional: "express" para Express Post (o padrão) ou "regular" para o correio comum.
duplexboolean · opcional: Imprime em frente e verso. O padrão é false. Declarações juramentadas (statutory declarations) são sempre impressas só na frente.
monoboolean · opcional: Imprime em preto e branco. O padrão é false: um documento que contém cores é impresso em cores.
stapleboolean · opcional: Grampeia as páginas uma vez no canto superior esquerdo. Só para documentos de até 12 páginas; um mais longo é recusado ao ser precificado. O padrão é false.
foldboolean · opcional: Somente Express Post: dobra a carta em um envelope C5, em vez de enviá-la sem dobrar em um B4, sem custo adicional. Ignorado em documentos com mais de 20 páginas, que seguem sem dobrar. As cartas do correio comum são sempre dobradas.
signatureboolean · opcional: Assinatura na entrega, 6 USDC a mais, em qualquer um dos serviços. Com regular, a carta segue pelo Correio registrado.

Endereço

O destinatário precisa estar na Austrália. O endereço de devolução pode ser em qualquer lugar: informe o país, e o código postal passa a ser opcional. Cada linha pode ter até 40 caracteres.

namestring · opcional: O nome completo da pessoa.
companystring · opcional: Uma empresa ou organização.
line1string · obrigatório: O endereço (rua e número), ou uma caixa postal, como "PO Box 123".
line2string · opcional: Uma segunda linha de endereço.
suburbstring · obrigatório: O bairro ou a cidade.
statestring · opcional: Na Austrália, deixe de fora: o código postal o define. Se informado, um destes: ACT, NSW, NT, QLD, SA, TAS, VIC ou WA, de acordo com o código postal.
postcodestring · obrigatório: Quatro dígitos.
countrystring · opcional: Somente no endereço de devolução. Deixe de fora para a Austrália.

Requisição

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
}'

Resposta 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"
}

Envie o documento

PUTuploadUrl

Faça um PUT dos bytes brutos do arquivo para a uploadUrl em até 15 minutos. Até 50 MB e 80 páginas. A diagramação em A4 começa assim que o upload chega; não há mais nada a chamar.

Requisição

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

Consultar uma carta

GET/api/x402/{jobId}

Aguarde o preço

Consulte a cada poucos segundos até que status seja ready_to_send. A resposta passa então a trazer o número de páginas, o preço em payment, a sendUrl e uma previewUrl do PDF pronto para impressão, para conferir antes de pagar.

Agora fold acompanha o serviço, true para o correio comum e false para o Express Post, e duplex pode ser false: declarações juramentadas são impressas só na frente. Uma carta do correio comum com mais de 12 páginas é rejeitada quando o preço é calculado.

Acompanhe a carta

Continue consultando, com menos frequência, até que a carta esteja posted e depois delivered. Não há e-mails; toda atualização aparece no status.

Requisição

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

Resposta 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"
}

Resposta 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 e poste

POST/api/x402/{jobId}/send

Faça um POST para a sendUrl sem pagamento. A resposta é 402 Payment Required, com os requisitos de pagamento codificados em base64 no cabeçalho PAYMENT-REQUIRED.

Assine o pagamento como descreve o protocolo x402 (ou deixe uma biblioteca cliente x402 fazer isso) e reenvie a requisição com o payload em um cabeçalho PAYMENT-SIGNATURE. Nós verificamos e liquidamos o pagamento, e a carta vai para impressão. O cabeçalho PAYMENT-RESPONSE traz a liquidação.

Recebeu 409 com job not ready to send logo depois de ready_to_send? Aguarde um instante e tente de novo. Chamar de novo depois de pagar retorna o status sem cobrar em dobro.

Requisição

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

Resposta 402

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

{
  "error": "payment required"
}

Cabeçalho PAYMENT-REQUIRED, decodificado de base64

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

Requisição

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

Resposta 202

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

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

Status

awaiting_upload: Aguardando o arquivo.
processing: Diagramando o documento em A4 e calculando o preço.
ready_to_send: Com preço definido e aguardando pagamento. A cotação vale por 7 dias.
sending: Paga e na fila de impressão.
retrying: A impressão teve um problema; estamos tentando de novo automaticamente.
posted: Impressa e postada na Australia Post.
delivered: Entregue pela Australia Post. O documento foi apagado na postagem.
failed: Não postada; o motivo está em error, como uma cotação que expirou sem pagamento. Uma carta paga que não pode ser postada é reembolsada integralmente.
refunded: O pagamento voltou para a carteira que o fez.

Erros

400: Requisição inválida: por exemplo, campo ausente, tipo de arquivo não suportado, linha de endereço com mais de 40 caracteres, código postal fora do estado, assinatura na entrega com o correio comum, ou carta do correio comum com mais de 12 páginas.
402: O pagamento é obrigatório, ou não foi possível verificá-lo ou liquidá-lo. error diz o motivo.
404: Não há carta com esse jobId.
409: job not ready to send: aguarde ready_to_send e tente de novo. quote expired: crie a carta novamente.

Perguntas frequentes

O que é x402?

Um protocolo aberto para pagar por HTTP. O servidor responde 402 Payment Required com um preço; o cliente assina um pagamento em stablecoin e reenvia a requisição. Sem conta, cartão ou fatura.

Do que eu preciso?

Uma carteira na Base com USDC suficiente e um cliente HTTP. Não é preciso ETH para o gas: o pagamento é uma autorização assinada de transferência de USDC, e nós cobrimos a taxa de rede.

Quanto custa uma carta?

20 USDC pelo Express Post para até 20 páginas, depois 0.30 USDC por página, ou 10 USDC pelo correio comum para uma carta de até 12 páginas, GST incluído. A assinatura na entrega custa 6 USDC a mais em qualquer um dos serviços; o correio comum com assinatura é o Correio registrado, 16 USDC. Rastreamento, impressão frente e verso e em preto e branco, grampeamento de até 12 páginas e a dobra de uma carta Express Post em envelope DL com janela são grátis. A resposta de status mostra o preço exato antes de você pagar.

Posso conferir a carta antes de pagar?

Sim. Quando ela está pronta para envio, previewUrl é o PDF pronto para impressão, diagramado em A4 exatamente como será impresso. Nada é cobrado até você pagar.

Quando ela é postada e quanto tempo leva para chegar?

As cartas pagas até as 14h30, horário de Melbourne, de um dia útil são postadas no mesmo dia; as demais, no dia útil seguinte. O Express Post costuma chegar no dia útil seguinte dentro da rede Express Post; o correio comum, em 3 a 7 dias úteis.

E se a carta não puder ser postada?

O status muda para failed e reembolsamos o valor integral em USDC à carteira pagadora, quer ela tenha falhado, quer a tenhamos cancelado. Para qualquer outro assunto, escreva para support@unopost.com.au com o jobId.

O que acontece com o meu documento?

Ele é criptografado em trânsito e apagado definitivamente, junto com a cópia pronta para impressão, assim que a carta é postada na Australia Post. Se uma carta não for paga ou não puder ser postada, ele é apagado após 14 dias.

Para onde as cartas podem ir?

Para qualquer endereço na Austrália, inclusive caixas postais (PO Boxes), em todos os estados e territórios. A API não envia ao exterior.

Quem responde pelo que um agente envia?

Você. Toda carta paga com a sua carteira é sua, inclusive uma que um agente escreveu e enviou seguindo suas instruções, e você precisa ter o direito de enviar o que ela contém. Nossos termos listam o que não pode ir pelo correio: falsidade de identidade, assédio, golpes, publicidade não solicitada em massa e qualquer coisa que viole uma ordem judicial. Cancelamos as cartas que descumprem essas regras e as reembolsamos integralmente. Se você envia em nome de outra pessoa, responde pelo documento dela como se fosse seu.

Preços

Item	Preço
Correio comum, dobrada para caber na caixa de correio: até 12 páginas	10 USDC
Correio registrado, o correio comum com assinatura na entrega: até 12 páginas	16 USDC
Express Post, sem dobrar em envelope B4: 20 páginas incluídas, depois 0.30 USDC por página adicional	20 USDC
Express Post com assinatura na entrega: 20 páginas incluídas, depois 0.30 USDC por página adicional	26 USDC
Rastreamento, impressão em cores, frente e verso ou preto e branco, e grampeamento	Grátis
Taxa de rede (gas)	Por nossa conta

Os preços são em USDC na Base. O preço é definido depois que seu documento é diagramado em A4; as cotações valem por 7 dias.

Os preços podem mudar. O uso deste serviço está sujeito aos nossos Termos de Serviço e à nossa Política de Privacidade.