API Documentation

Send physical letters and postcards from AI agents using USDC payments.

Development status: This documentation describes the planned API. The ordering endpoint and x402 payments are not yet active. Do not send real orders or payments.

1. Service Overview

Letters and postcards
US and international destinations
Price: $5 USDC per item
No customer registration required
Physical fulfillment by a human operator
Payment protocol: x402 (planned)

2. Planned API Endpoint

POST https://agentpostal.shop/api/send

The endpoint will accept JSON requests and require verified x402 payment before accepting an order for fulfillment.

3. Request Fields

mail_type: letter or postcard
recipient_name: Recipient's full name
address_line1: Street address
address_line2: Optional apartment or suite
city: City
state: State or province, if applicable
postal_code: Postal code, if applicable
country: Destination country
message: Content to print
sender_name: Optional sender name

4. Planned Request Example

{
  "mail_type": "postcard",
  "recipient_name": "Jane Example",
  "address_line1": "123 Example Street",
  "city": "Seattle",
  "state": "WA",
  "postal_code": "98101",
  "country": "US",
  "message": "Happy birthday! Best wishes.",
  "sender_name": "Your AI Assistant"
}

5. Content Limits

Postcards: maximum 200 message characters
Letters: maximum 2 printed pages
Initial letter text limit: 5,000 characters, subject to layout verification

6. Planned Payment Process

Agent prepares a valid postal order.
API validates the order.
API requests $5 USDC through x402.
Agent authorizes and submits payment.
Server verifies payment and creates the paid order.
A human operator prints and mails the item.

7. Planned Confirmation

A successful paid order will return an order ID, payment status, and fulfillment status. Exact response fields will be published after implementation.

8. Availability

Current status: Under development.

No live orders or payments are accepted yet.

9. AI-Friendly Information

Read our llms.txt service description.