x402 API
코드에서 편지를 보내고 USDC로 결제
앱과 AI 에이전트가 호주 어디로든 편지를 보내고 x402를 통해 편지마다 USDC로 결제할 수 있습니다. 계정, API 키, 구독이 필요 없습니다. 지갑과 HTTP 클라이언트만 있으면 됩니다.
10 USDC 일반 우편 1통당20 USDC Express Post 1통당
접지 않고 최대 20페이지까지 단일 가격, GST 포함. Base의 USDC로 결제하며 가스비는 저희가 부담합니다.
왜 x402로 편지를 보내나요?
웹사이트와 똑같은 편지를 HTTP로 결제합니다.
- 계정도 API 키도 필요 없음 가입할 것이 없습니다. 코드가 편지를 만들고, 가격을 받고, 서명한 USDC 결제로 지불합니다.
- 편지 1통당 고정 가격 접지 않고 B4 봉투로 보내는 Express Post는 20 USDC, 우편함에 들어가도록 접어서 보내는 일반 우편은 10 USDC입니다. 접어서 최대 12페이지 또는 접지 않고 20페이지까지 인쇄, 봉투, 우편 요금, 배송 조회가 포함되며, 이후 페이지당 0.30 USDC입니다. GST 포함이며 가스비는 저희가 냅니다.
- 웹사이트와 똑같은 편지 올린 그대로 80gsm A4 용지에 인쇄하고, 배송 조회가 가능하며, 멜버른 시간 오후 2시 30분까지 결제하면 같은 영업일에 발송합니다.
- 발송할 수 없으면 환불 발송할 수 없으면 결제한 지갑으로 전액을 USDC로 환불합니다. 저희가 취소한 편지도 같은 방식으로 환불합니다.
누구를 위한 것인가요
- AI 에이전트 보증금 분쟁, 보험 청구, 지자체 민원을 처리하는 에이전트가 직접 편지를 보내고 자기 지갑에서 결제할 수 있습니다.
- 앱과 스크립트 가맹점 계정이나 월 요금제 없이 편지를 보내는 부동산 관리, 법률, 청구 소프트웨어.
빠른 시작
요청 다섯 번이면 코드에서 우체국까지 편지가 갑니다. 계정도 키도 없습니다. 결제만 있으면 됩니다.
# 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 사양.
https://unopost.com.au편지 생성
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 · 선택- 페이지 왼쪽 위 모서리를 스테이플러로 한 번 고정합니다. 최대 12페이지 문서에만 가능하며, 그보다 긴 문서는 가격을 계산할 때 거부됩니다. 기본값은
false입니다. foldboolean · 선택- Express Post 전용: 추가 비용 없이, 접지 않고 B4 봉투로 보내는 대신 접어서 C5 봉투에 넣습니다. 20페이지가 넘는 문서에는 무시되며 접지 않고 발송합니다. 일반 우편 편지는 항상 접습니다.
signatureboolean · 선택- 수령 시 서명. 두 서비스 모두 6 USDC 추가입니다.
regular와 함께 쓰면 편지는 등기 우편으로 발송됩니다.
주소
받는 사람은 호주에 있어야 합니다. 반송 주소는 어느 나라든 가능합니다. 국가를 지정하면 우편번호는 선택 사항이 됩니다. 각 줄은 최대 40자입니다.
namestring · 선택- 사람의 성명.
companystring · 선택- 사업체 또는 단체.
line1string · 필수- 도로명 주소, 또는
"PO Box 123"같은 PO Box. line2string · 선택- 주소 둘째 줄.
suburbstring · 필수- 서버브(suburb) 또는 타운.
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
}'{
"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{
"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"
}{
"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/sendHTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi...
{
"error": "payment required"
}{
"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"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의 편지가 없습니다. 409job not ready to send:ready_to_send가 될 때까지 기다렸다가 다시 시도하세요.quote expired: 편지를 다시 생성하세요.
자주 묻는 질문
x402란 무엇인가요?
HTTP로 결제하기 위한 개방형 프로토콜입니다. 서버가 가격과 함께 402 Payment Required로 응답하면, 클라이언트가 스테이블코인 결제에 서명해 요청을 다시 보냅니다. 계정도, 카드도, 청구서도 필요 없습니다.
무엇이 필요한가요?
USDC가 충분히 들어 있는 Base 지갑과 HTTP 클라이언트입니다. 가스비로 쓸 ETH는 필요 없습니다. 결제는 서명된 USDC 전송 승인이며, 네트워크 수수료는 저희가 부담합니다.
편지 한 통에 얼마인가요?
Express Post는 최대 20페이지까지 20 USDC, 이후 페이지당 0.30 USDC이고, 일반 우편은 최대 12페이지 편지에 10 USDC이며, GST 포함입니다. 수령 시 서명은 두 서비스 모두 6 USDC 추가이며, 수령 시 서명을 받는 일반 우편은 등기 우편으로 16 USDC입니다. 배송 조회, 양면 인쇄와 흑백 인쇄, 최대 12페이지의 스테이플러 고정, Express Post 편지를 접어 DL 창봉투에 넣는 것은 무료입니다. 결제 전에 상태 응답에서 정확한 가격을 확인할 수 있습니다.
결제 전에 편지를 확인할 수 있나요?
네. 발송 준비가 되면 previewUrl에서 인쇄될 모습 그대로 A4에 배치된 인쇄용 PDF를 볼 수 있습니다. 결제하기 전에는 아무것도 청구되지 않습니다.
언제 발송되고, 도착까지 얼마나 걸리나요?
영업일에 멜버른 시간 오후 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페이지 포함, 이후 추가 페이지당 0.30 USDC | 20 USDC |
| 수령 시 서명을 받는 Express Post: 20페이지 포함, 이후 추가 페이지당 0.30 USDC | 26 USDC |
| 배송 조회, 컬러, 양면 또는 흑백 인쇄, 스테이플러 고정 | 무료 |
| 네트워크 수수료(가스비) | 저희 부담 |
가격은 Base의 USDC 기준입니다. 가격은 문서를 A4에 맞춰 배치한 뒤 정해지며, 견적은 7일간 유효합니다.