x402 API

コードから手紙を郵送、USDCで支払い

アプリやAIエージェントが、オーストラリア国内のどこへでも手紙を郵送し、x402を通じて1通ごとにUSDCで支払えます。アカウントも、APIキーも、定額プランも不要です。必要なのはウォレットとHTTPクライアントだけです。

10 USDC 普通郵便、1通あたり20 USDC Express Post、1通あたり

折らずに20ページまで一律料金、GST込み。Base上のUSDCで支払い、ガス代は当社負担。

クイックスタート OpenAPI仕様

なぜx402で手紙を送るのか

ウェブサイトと同じ手紙を、HTTPで支払って送れます。

アカウントもAPIキーも不要 登録は必要ありません。コードが手紙を作成し、料金を取得し、署名したUSDC決済で支払います。
1通ごとの固定料金 B4封筒で折らずに送るExpress Postは20 USDC、郵便受けに入るよう折りたたむ普通郵便は10 USDC。印刷、封筒、郵便料金、追跡を含み、折りたたみで12ページまで、折らずに20ページまで、以降は1ページ0.30 USDCです。GST込みで、ガス代は当社が負担します。
ウェブサイトと同じ手紙 アップロードされたとおりに80gsmのA4用紙に印刷し、追跡付きで、午後2時30分（メルボルン時間）までにお支払いいただければ当営業日に発送します。
発送できなければ返金 発送できない場合は、支払い元のウォレットにUSDCで全額を返金します。当社がキャンセルした手紙も同じ方法で返金します。

こんな用途に

AIエージェント 敷金（ボンド）をめぐる争い、保険金の請求、地方自治体への苦情などを扱うエージェントが、自ら手紙を郵送し、自身のウォレットから支払えます。
アプリとスクリプト 手紙を郵送する不動産管理、法務、請求のソフトウェアに。加盟店アカウントも月額プランも不要です。

5つのリクエストで、コードから投函まで完了します。アカウントもキーもありません。必要なのは支払いだけです。

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}/sendUSDCで支払うと、手紙が印刷に回ります。

手紙を作成する

POST/api/x402

ファイル名、受取人の住所、差出人住所をPOSTします。jobId、署名付きのuploadUrl、手紙の確認用と支払い用のURLが返ります。

リクエストボディ

fileNamestring · 必須: 拡張子付きのファイル名：.pdf、.doc、.docx、.jpg、.jpeg、.png のいずれか。
recipientAddress · 必須: 手紙の郵送先の住所。
senderAddress · 必須: お客様の差出人住所。封筒に印刷され、配達できなかった郵便物がここに戻ります。
servicestring · 任意: Express Postなら"express"（既定値）、普通郵便なら"regular"。
duplexboolean · 任意: 両面で印刷します。既定値はfalseです。法定宣誓書（statutory declaration）は常に片面印刷です。
monoboolean · 任意: 白黒で印刷します。既定値はfalseで、カラーを含む書類はカラーで印刷されます。
stapleboolean · 任意: ページの左上を1か所ホチキス留めします。12ページまでの書類のみ対象で、それより長い書類は料金計算時に拒否されます。既定値はfalseです。
foldboolean · 任意: Express Postのみ：B4封筒で折らずに送る代わりに、追加料金なしで手紙を折りたたんでC5封筒に入れます。20ページを超える書類では無視され、折らずに送られます。普通郵便の手紙は常に折りたたみます。
signatureboolean · 任意: 配達時の署名。どちらのサービスでも6 USDCの追加です。regularの場合、手紙は書留郵便で発送されます。

住所

受取人はオーストラリア国内に限ります。差出人住所はどの国でもかまいません。国を指定すると、郵便番号は省略可能になります。各行は40文字までです。

namestring · 任意: 個人の氏名。
companystring · 任意: 会社名または団体名。
line1string · 必須: 番地と通りの名前、または"PO Box 123"のようなPO Box。
line2string · 任意: 住所の2行目。
suburbstring · 必須: サバーブ（地区）または町の名前。
statestring · 任意: オーストラリアの住所では省略してください。郵便番号から決まります。指定する場合は、ACT、NSW、NT、QLD、SA、TAS、VIC、WAのいずれかで、郵便番号と一致している必要があります。
postcodestring · 必須: 4桁の数字。
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分以内に、ファイルの生のバイト列をuploadUrlへPUTします。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の直後に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を返し、クライアントがステーブルコインでの支払いに署名してリクエストを再送します。アカウントも、カードも、請求書も不要です。

何が必要ですか？

十分なUSDCが入ったBase上のウォレットと、HTTPクライアントです。ガス代のためのETHは必要ありません。支払いは署名付きのUSDC送金承認であり、ネットワーク手数料は当社が負担します。

手紙1通の料金はいくらですか？

Express Postなら20ページまで20 USDC、以降1ページ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で全額を返金します。それ以外のご用件は、jobIdを添えて support@unopost.com.au までメールでご連絡ください。

書類はどう扱われますか？

通信中は暗号化され、手紙がAustralia Postに差し出されると、印刷用のコピーとともに完全に削除されます。手紙の支払いがない場合や発送できない場合は、14日後に削除されます。

手紙はどこへ送れますか？

オーストラリアのすべての州・準州の、PO Box（私書箱）を含むあらゆる住所です。このAPIでは海外へは発送できません。

エージェントが送ったものの責任は誰にありますか？

お客様にあります。お客様のウォレットから支払われた手紙は、お客様の指示でエージェントが作成して送ったものも含め、すべてお客様の手紙であり、その内容を送る権利がお客様にあることが必要です。郵送できないものは当社の利用規約に定めています。なりすまし、嫌がらせ、詐欺、大量の迷惑広告、裁判所の命令に違反するものなどです。これらの規則に違反する手紙はキャンセルし、全額を返金します。他人に代わって郵送する場合、その書類についても、ご自身のものと同じように責任を負います。

料金

項目	料金
普通郵便、郵便受けに入るよう折りたたみ：12ページまで	10 USDC
書留郵便（配達時の署名付きの普通郵便）：12ページまで	16 USDC
Express Post、B4封筒で折らずに：20ページまで込み、以降1ページごとに0.30 USDC	20 USDC
Express Post、配達時の署名付き：20ページまで込み、以降1ページごとに0.30 USDC	26 USDC
追跡、カラー印刷、両面印刷、白黒印刷、ホチキス留め	無料
ネットワーク手数料（ガス代）	当社負担

料金はBase上のUSDC建てです。料金は書類をA4にレイアウトした時点で確定し、見積もりは7日間有効です。

料金は変更されることがあります。本サービスのご利用には、当社の利用規約とプライバシーポリシーが適用されます。