x402 API

用代码寄信，用 USDC 付款

应用和 AI 智能体可以把信寄到澳大利亚任何地方，通过 x402 以 USDC 按封付款。无需账户、API 密钥或订阅：只要一个钱包和一个 HTTP 客户端。

10 USDC 普通邮件每封20 USDC Express Post 每封

平放最多 20 页，一口价，含 GST。在 Base 上以 USDC 支付，gas 由我们承担。

快速入门 OpenAPI 规范

为什么通过 x402 寄信？

与网站寄出的信件相同，只是通过 HTTP 付款。

无需账户或 API 密钥 不用注册。您的代码创建信件、获取价格，再用一笔签名的 USDC 付款完成支付。
每封信固定价格 Express Post 20 USDC，平放装入 B4 信封；普通邮件 10 USDC，折叠后可投入信箱。价格包含打印、信封、邮资和追踪，折叠最多 12 页，平放最多 20 页，之后每页 0.30 USDC。含 GST，gas 由我们承担。
与网站寄出的信件相同 按上传内容用 80gsm A4 纸打印，可追踪；在工作日墨尔本时间 14:30 前付款，同一工作日寄出。
无法寄出即退款 如果我们无法寄出，会以 USDC 全额退款到付款钱包。被我们取消的信件也以同样方式退款。

适合谁用

AI 智能体 处理押金纠纷、保险理赔或市政投诉的智能体可以自己寄信，并从自己的钱包付款。
应用和脚本 需要寄信的物业管理、法律和账单软件，无需商户账户或月度套餐。

五个请求，把一封信从您的代码送到邮局。没有账户，也没有密钥：我们只需要付款。

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"

端点

端点路径均相对于 https://unopost.com.au。请求和响应均为 JSON；错误格式为 {"error": "..."}。完整参考：OpenAPI 规范。

基础 URL

https://unopost.com.au

POST/api/x402创建信件。免费。PUTuploadUrl把文件上传到信件的签名链接。GET/api/x402/{jobId}获取信件的状态、价格和追踪信息。POST/api/x402/{jobId}/send用 USDC 付款，信件随即送去打印。

创建信件

POST/api/x402

POST 文件名、收件人地址和您的退信地址。您会得到一个 jobId、一个签名的 uploadUrl，以及用于查询信件和付款的 URL。

请求体

fileNamestring · 必填: 带扩展名的文件名：.pdf、.doc、.docx、.jpg、.jpeg 或 .png。
recipientAddress · 必填: 信件的收件地址。
senderAddress · 必填: 您的退信地址，印在信封上，无法投递的邮件才能退回给您。
servicestring · 可选: "express" 表示 Express Post（默认），"regular" 表示普通邮件。
duplexboolean · 可选: 双面打印。默认为 false。法定声明（statutory declaration）一律单面打印。
monoboolean · 可选: 黑白打印。默认为 false：含有彩色内容的文件以彩色打印。
stapleboolean · 可选: 在左上角将页面装订一次。仅适用于不超过 12 页的文件；超出的文件会在计价时被拒绝。默认为 false。
foldboolean · 可选: 仅限 Express Post：把信件折叠装入 C5 信封，而不是平放装入 B4 信封寄出，不另收费。超过 20 页的文件忽略此项，一律平放寄出。普通邮件一律折叠。
signatureboolean · 可选: 投递时签收，另收 6 USDC，两种服务均可选。与 regular 一起使用时，信件以挂号邮件寄出。

地址

收件人必须在澳大利亚境内。退信地址可以在任何地方：填写其国家后，邮编即变为选填。每行最多 40 个字符。

namestring · 可选: 收件人全名。
companystring · 可选: 企业或机构名称。
line1string · 必填: 街道地址，或 PO Box，例如 "PO Box 123"。
line2string · 可选: 地址第二行。
suburbstring · 必填: 城区或城镇。
statestring · 可选: 澳大利亚地址请省略：由邮编决定。如果填写，须为 ACT、NSW、NT、QLD、SA、TAS、VIC 或 WA 之一，并与邮编相符。
postcodestring · 必填: 四位数字。
countrystring · 可选: 仅用于退信地址。澳大利亚地址请省略。

请求

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

响应 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"
}

上传文件

PUTuploadUrl

在 15 分钟内把文件的原始字节 PUT 到 uploadUrl。最大 50 MB、80 页。上传一完成就开始按 A4 排版；不需要再调用别的接口。

请求

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

查询信件

GET/api/x402/{jobId}

等待报价

每隔几秒轮询一次，直到 status 变为 ready_to_send。这时响应中会有页数、payment 中的价格、sendUrl，以及指向可打印 PDF 的 previewUrl，供付款前检查。

此时 fold 随服务而定，普通邮件为 true，Express Post 为 false；duplex 可能为 false：法定声明以单面打印。超过 12 页的普通邮件会在计价时被拒绝。

追踪信件

继续轮询，频率可以降低，直到信件变为 posted，随后变为 delivered。不会发送电子邮件；每次更新都体现在状态中。

请求

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

响应 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"
}

响应 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"
}

付款并邮寄

POST/api/x402/{jobId}/send

不带付款信息向 sendUrl 发送 POST。响应为 402 Payment Required，付款要求以 base64 编码放在 PAYMENT-REQUIRED 响应头中。

按 x402 协议的说明对付款签名（或交给 x402 客户端库处理），然后重新发送请求，把载荷放在 PAYMENT-SIGNATURE 请求头中。我们验证并结算后，信件随即送去打印。PAYMENT-RESPONSE 响应头中有结算信息。

刚看到 ready_to_send 就收到带 job not ready to send 的 409？稍等片刻再重试。付款后再次调用会返回状态，不会重复扣费。

请求

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

响应 402

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

{
  "error": "payment required"
}

PAYMENT-REQUIRED 标头，base64 解码后

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

请求

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

响应 202

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

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

状态

awaiting_upload: 等待文件上传。
processing: 正在把文件按 A4 排版并计价。
ready_to_send: 已计价，等待付款。报价有效期为 7 天。
sending: 已付款，排队等待打印。
retrying: 打印遇到问题；我们正在自动重试。
posted: 已打印并交寄 Australia Post。
delivered: Australia Post 已送达。文件已在寄出时删除。
failed: 未寄出；原因见 error，例如报价过期未付款。已付款但无法寄出的信件会全额退款。
refunded: 款项已退回到付款的钱包。

错误

400: 无效请求：例如缺少字段、文件类型不受支持、地址行超过 40 个字符、邮编不在所填的州内、普通邮件加选签收或普通邮件超过 12 页。
402: 需要付款，或付款无法验证或结算。error 会说明原因。
404: 没有该 jobId 对应的信件。
409: job not ready to send：请等到 ready_to_send 后重试。quote expired：请重新创建信件。

常见问题

什么是 x402？

一种通过 HTTP 付款的开放协议。服务器以 402 Payment Required 回复并给出价格；客户端对一笔稳定币付款签名，然后重新发送请求。无需账户、银行卡或发票。

我需要准备什么？

一个在 Base 上有足够 USDC 的钱包，以及一个 HTTP 客户端。不需要用 ETH 付 gas：付款是一份签名的 USDC 转账授权，网络费由我们承担。

寄一封信多少钱？

Express Post 20 USDC，最多 20 页，之后每页 0.30 USDC；普通邮件 10 USDC，最多 12 页。均含 GST。两种服务加选签收均另收 6 USDC；普通邮件加选签收即为挂号邮件，16 USDC。追踪、双面和黑白打印、不超过 12 页的装订，以及把 Express Post 信件折叠装入 DL 开窗信封，都是免费的。状态响应会在您付款前显示确切价格。

付款前可以检查信件吗？

可以。信件就绪后，previewUrl 指向可打印的 PDF，按 A4 排版，与实际打印效果完全一致。付款之前不收取任何费用。

什么时候寄出？多久能到？

在工作日墨尔本时间 14:30 前付款的信件当天寄出；之后付款的，下一个工作日寄出。Express Post 在 Express Post 网络范围内通常下一个工作日送达，普通邮件需 3 至 7 个工作日。

如果信件无法寄出怎么办？

状态会变为 failed，无论是寄送失败还是被我们取消，我们都会以 USDC 全额退款到付款钱包。其他问题请发邮件至 support@unopost.com.au 并附上 jobId。

我的文件会怎样处理？

文件在传输过程中经过加密；信件交寄 Australia Post 后，文件连同其可打印副本即被永久删除。如果信件未付款或无法寄出，则在 14 天后删除。

信件可以寄到哪里？

澳大利亚各州和领地的任何地址，包括 PO Box。此 API 不寄往海外。

智能体寄出的内容由谁负责？

由您负责。从您的钱包付款的每封信都是您的信，包括智能体按您的指示撰写并寄出的信，而且您必须有权寄送其中的内容。我们的服务条款列明了不得邮寄的内容：冒充他人、骚扰、诈骗、大批量未经请求的广告，以及任何违反法院命令的内容。违反这些规则的信件我们会取消，并全额退款。如果您代他人寄信，您须对其文件负责，如同那是您自己的文件。

价格

项目	价格
普通邮件，折叠后可投入信箱：最多 12 页	10 USDC
挂号邮件，即投递时签收的普通邮件：最多 12 页	16 USDC
Express Post，平放装入 B4 信封：含 20 页，之后每加一页 0.30 USDC	20 USDC
Express Post 加选签收：含 20 页，之后每加一页 0.30 USDC	26 USDC
追踪、彩色、双面或黑白打印，以及装订	免费
网络费（gas）	由我们承担

价格以 Base 上的 USDC 计。文件按 A4 排版后才确定价格；报价有效期为 7 天。

价格可能变动。使用本服务须遵守我们的服务条款和隐私政策。