API Reference

POST Token API v1.2

Complete API documentation for integrating with POST Token. Includes Transaction-Linked Conversion, Vesting API, and comprehensive error codes.

Base URL: https://api.post.network

Version 1.2.0

Overview

Authentication

Rate Limiting

Gateway API

Vesting API

Transaction API

Token API

Calculator API

Error Codes

Overview

Base configuration and request format

Base URLs

Production	`https://api.post.network`
Staging	`https://api.staging.post.network`
Development	`http://localhost:8787`

Request Headers

HTTP

Content-Type: application/json
Accept: application/json
Accept-Language: en

Response Format

Success Response

JSON

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "pageSize": 10
  }
}

Error Response

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": { ... }
  }
}

Authentication

Turnstile and Operator token authentication

Turnstile (Public)

For public endpoints like contact forms. Include the Turnstile token in the request body.

JSON

{
  "turnstileToken": "0.xxxxx..."
}

Operator Token

For operator endpoints (vesting, transactions). Include in headers.

HTTP

Authorization: Bearer <operator_token>
X-Operator-Code: <country_code>

Token Generation

HTTP

1POST /api/auth/token
2Content-Type: application/json
3 
4{
5  "operator_code": "USPS",
6  "api_key": "sk_live_xxxxx",
7  "grant_type": "client_credentials"
8}
9 
10// Response
11{
12  "access_token": "eyJhbGciOiJIUzI1NiIs...",
13  "token_type": "Bearer",
14  "expires_in": 3600,
15  "scope": "gateway:swap vesting:read transactions:write"
16}

Rate Limiting

API and vesting rate limits

API Rate Limits

Endpoint	Limit	Window
`GET /*`	1000	1 hour
`POST /api/gateway/swap`	100	1 hour
`POST /api/vesting/sell`	10	1 hour
`POST /api/contact/*`	5	1 hour

Vesting Rate Limits

Limit Type	Per Country	Network
Daily	10,000 POST	5,000,000 POST
Weekly	50,000 POST	25,000,000 POST
Monthly	200,000 POST	100,000,000 POST
Annual	2,500,000 POST	500,000,000 POST

Gateway API v1.2

POST ↔ PSDR token conversion

Critical Change in v1.2

POST → PSDR swap now requires a valid transaction_id. PSDR can only be minted when a real postal transaction exists. PSDR → POST remains unrestricted.

GET

/api/gateway/rate

Get Exchange Rate

Get the current POST/PSDR exchange rate and SDR pricing.

No parameters required for this endpoint.

POST

/api/gateway/swap

Swap POST to PSDR

Convert POST tokens to PSDR. Requires a valid transaction_id from the Transaction API.

Auth:

Operator Token

Important

This endpoint REQUIRES a valid transaction_id. PSDR cannot be created without a real postal transaction.

Parameters

Name	Type	Required	Description
`postAmount`	number	Required	Amount of POST to swap
`transactionId`	string	Required	Transaction ID from /api/transactions/create (e.g., TRF-2026-01-14-ABC123)
`transactionType`	string	Required	Type of transaction
`minPsdrReceive`	number	Optional	Minimum PSDR to receive (slippage protection)

application/json

1{
"postAmount": 40.816,
"transactionId": "TRF-2026-01-14-ABC123",
"transactionType": "MoneyTransfer",
"minPsdrReceive": 74.0,
"recipientWallet": "post1recipient...",
"operatorCode": "US"
8}

Response

1{
"success": true,
"data": {
  "swapId": "swp_xyz789",
  "transactionId": "TRF-2026-01-14-ABC123",
  "postAmount": 40.816,
  "psdrAmount": 74.626,
  "swapRate": 1.83,
  "swapFee": 0.373,
  "status": "completed",
  "transactionHash": "0xabc...",
  "transactionStatus": "FUNDED"
}
14}

Code	HTTP Status	Message
`E001`	400	Invalid transaction ID
`E002`	400	Transaction not pending
`E006`	400	Slippage exceeded
`E007`	400	Transaction expired

POST

/api/gateway/swap-out

Swap PSDR to POST

Convert PSDR back to POST. No transaction_id required (unrestricted cash-out flow).

Auth:

Operator Token

Parameters

Name	Type	Required	Description
`psdrAmount`	number	Required	Amount of PSDR to swap
`minPostReceive`	number	Optional	Minimum POST to receive

application/json

1{
2  "psdrAmount": 100,
3  "minPostReceive": 54.0,
4  "recipientWallet": "post1abc..."
5}

Response

1{
"success": true,
"data": {
  "swapId": "swp_out_123",
  "psdrAmount": 100,
  "postAmount": 54.64,
  "swapRate": 1.83,
  "swapFee": 0.27,
  "status": "completed",
  "transactionHash": "0xdef..."
}
12}

Vesting API

Country airdrop allocations and controlled release

GET

/api/vesting/country/{countryCode}

Get Country Allocation

Query vesting status for a specific country including allocation details and rate limits.

Auth:

Operator Token

Parameters

Name	Type	Required	Description
`countryCode`	string	Required	ISO 3166-1 alpha-2 country code (e.g., TV)

POST

/api/vesting/sell

Execute Airdrop Sale

Sell POST from country airdrop allocation. Subject to rate limits.

Auth:

Operator Token

Rate Limit:

10 requests/hour

Parameters

Name	Type	Required	Description
`countryCode`	string	Required	Country code
`amount`	number	Required	Amount of POST to sell

application/json

1{
2  "countryCode": "TV",
3  "amount": 5000,
4  "recipientAddress": "0xExchangeAddress...",
5  "operatorSignature": "sig_xxx..."
6}

Response

1{
"success": true,
"data": {
  "saleId": "sale_abc123",
  "countryCode": "TV",
  "amount": 5000,
  "transactionHash": "0xdef...",
  "status": "completed",
  "updatedLimits": {
    "dailyRemaining": 0,
    "weeklyRemaining": 20000
  }
}
14}

Code	HTTP Status	Message
`E101`	429	Daily limit exceeded
`E102`	429	Weekly limit exceeded
`E107`	400	Insufficient vested amount

Transaction API

Create and manage transactions for Transaction-Linked Conversion

Transaction Lifecycle

TEXT

Transaction Lifecycle:
 
  CREATE                FUND                 COMPLETE
    │                    │                      │
    ▼                    ▼                      ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  PENDING    │───▶│   FUNDED    │───▶│  COMPLETED  │
│  FUNDING    │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘
    │
    │ (24h timeout)
    ▼
┌─────────────┐
│   EXPIRED   │
└─────────────┘

POST

/api/transactions/create

Create Transaction

Create a new transaction. Required before POST → PSDR conversion.

Auth:

Operator Token

Note

The returned transaction_id is required for the /api/gateway/swap endpoint.

Parameters

Name	Type	Required	Description
`transactionType`	string	Required	Type: MoneyTransfer, PostalShipment, MerchantPayment, etc.
`amount`	number	Required	Transaction amount
`currency`	string	Required	Currency code (USD, EUR, etc.)

application/json

1{
"transactionType": "MoneyTransfer",
"amount": 100,
"currency": "USD",
"senderRef": "customer_123",
"recipientRef": "recipient_456",
"operatorCode": "US",
"metadata": {
  "originCountry": "US",
  "destinationCountry": "PH"
}
12}

Response

1{
"success": true,
"data": {
  "transactionId": "TRF-2026-01-14-ABC123",
  "transactionType": "MoneyTransfer",
  "status": "PENDING_FUNDING",
  "amount": 100,
  "currency": "USD",
  "createdAt": "2026-01-14T10:00:00Z",
  "expiresAt": "2026-01-14T11:00:00Z",
  "nextStep": "Call POST /api/gateway/swap with this transactionId"
}
13}

GET

/api/transactions/{transactionId}

Get Transaction

Query transaction status and details.

Auth:

Operator Token

Parameters

Name	Type	Required	Description
`transactionId`	string	Required	Transaction ID

Error Codes

Complete error code reference

Code	Status	Message	Resolution
`E001`	400	Invalid transaction ID	Provide valid transaction_id
`E002`	400	Transaction not pending	Transaction must be PENDING_FUNDING
`E003`	400	Transaction type mismatch	Type must match request
`E006`	400	Slippage exceeded	Minimum receive not met
`E007`	400	Transaction expired	Create new transaction
`E008`	400	Insufficient balance	Add more POST tokens
`E009`	500	Pool imbalance	Try again later

Code	Status	Message	Resolution
`E101`	429	Daily limit exceeded	Wait until daily reset
`E102`	429	Weekly limit exceeded	Wait until weekly reset
`E103`	429	Monthly limit exceeded	Wait until monthly reset
`E107`	400	Insufficient vested amount	Amount exceeds vested tokens
`E108`	400	Invalid country code	Use valid ISO 3166-1 code
`E109`	403	Operator not authorized	Check operator permissions

Code	Status	Message
`E201`	400	Invalid transaction type
`E202`	400	Transaction creation failed
`E203`	404	Transaction not found
`E204`	400	Transaction already funded
`E205`	400	Self-transfer not allowed

Code	Status	Description
`VALIDATION_ERROR`	400	Request validation failed
`UNAUTHORIZED`	401	Authentication required
`TURNSTILE_FAILED`	403	Turnstile verification failed
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Internal server error