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 紙列印，可追蹤；在工作天墨爾本時間下午 2: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

不附付款，以 POST 請求 sendUrl。回應為 402 Payment Required，付款要求以 base64 編碼放在 PAYMENT-REQUIRED 標頭中。

依 x402 協定的說明簽署付款（或交由 x402 用戶端程式庫處理），再將承載內容放入 PAYMENT-SIGNATURE 標頭重新傳送請求。我們驗證並完成結算後，信件隨即送印。PAYMENT-RESPONSE 標頭中有結算資訊。

剛出現 ready_to_send 就收到 409 與 job not ready to send？請稍候再重試。付款後再次呼叫只會回傳狀態，不會重複扣款。

請求

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 頁為 20 USDC，之後每頁 0.30 USDC；普通郵件最多 12 頁為 10 USDC，含 GST。兩種服務加選簽收皆另加 6 USDC；需簽收的普通郵件即為掛號郵件，16 USDC。追蹤、雙面與黑白列印、12 頁以內的裝訂，以及將 Express Post 信件摺疊裝入 DL 開窗信封，皆免費。狀態回應會在您付款前顯示確切價格。

付款前可以先檢查信件嗎？

可以。信件就緒可寄出後，previewUrl 即為可列印的 PDF，已排版成 A4，與實際列印結果完全相同。在您付款之前不會收取任何費用。

信件何時寄出？多久會送達？

在工作天墨爾本時間下午 2: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 天。

價格可能變動。使用本服務須遵守我們的服務條款與隱私權政策。