API Documentation

MailStore · Orders / Inquiry / Payment

Overview

This documentation is intended for AI Agents and third-party systems, describing how to automate product browsing, order creation, and payment confirmation via HTTP API.

All endpoints return JSON. No authentication required.

Base URL

# Replace {base_url} with your actual deployment URL
api.php

General Rules

RuleDescription
Request BodyContent-Type: application/json
Responseapplication/json; charset=utf-8
EncodingUTF-8
CORSAll origins allowed
AuthNone, all endpoints are public

Error Response Format

{
  "error": "Error description",
  "code": "ERROR_CODE"
}
Status CodeMeaning
400Bad request (insufficient stock, invalid email, etc.)
404Resource not found (product or order does not exist)

Endpoints

GET /api.php/products
List products with optional filtering by tag, category, price, and stock
GET /api.php/products/{id}
Get a single product's details
POST /api.php/orders
Create an order, deduct stock, return USDT payment address
GET /api.php/orders/{id}
Query order status (pending / paid / delivered)
POST /api.php/orders/{id}/pay
Confirm an order has been paid (called by AI Agent after on-chain verification)

Step 1 · Browse Products

GET /api.php/products

Query Parameters (optional)

ParameterTypeExampleDescription
tagstring?tag=USA&tag=2FAFilter by tags (can repeat)
catstring?cat=GmailFilter by category
qstring?q=oldSearch name/tags
featuredint?featured=1Featured products only
min_pricefloat?min_price=1Minimum price
max_pricefloat?max_price=10Maximum price
stock_minint?stock_min=100Minimum stock
sortstring?sort=price_ascSort order

Sort Options

ValueDescription
defaultFeatured first > Stock desc > Price asc
price_ascPrice low → high
price_descPrice high → low
stock_descStock high → low
stock_ascStock low → high
name_ascName A-Z
newestNewest first

Example Request

# Query all Gmail products priced $1-$5 with stock available
curl -s "api.php/products?cat=Gmail&min_price=1&max_price=5&stock_min=1"

Example Response

{
  "products": [
    {
      "id": 2844,
      "name": "Buy Gmail accounts (USA IP | 2FA | PVA)",
      "tags": ["USA", "2FA", "PVA"],
      "price": 1.50,
      "stock": 342,
      "image": "https://www.gstatic.com/...",
      "category": "Gmail",
      "featured": false
    }
  ],
  "total": 340
}

Step 2 · Place an Order

POST /api.php/orders
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
product_idintRequiredProduct ID (from products list)
quantityintRequiredQuantity (≥1)
emailstringRequiredEmail to receive the accounts

Example Request

curl -s -X POST api.php/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": 2844,
    "quantity": 10,
    "email": "[email protected]"
  }'

Response 201 (Success)

{
  "order_id": 42,
  "total": 15.00,
  "product_name": "Buy Gmail accounts (USA IP | 2FA | PVA)",
  "quantity": 10,
  "unit_price": 1.50,
  "usdt_address": "TNCer1PzKopxcg26zj1Ao84n6Yp9BuUpPR",
  "usdt_network": "TRC-20",
  "status": "pending"
}

Response Fields

FieldDescription
order_idOrder ID, used for status queries and payment confirmation
totalTotal amount due (USD)
usdt_addressUSDT payment address (TRC-20)
usdt_networkNetwork type
statusAlways returns "pending"

Error Responses

# 400 - Insufficient stock
{ "error": "Insufficient stock", "code": "INSUFFICIENT_STOCK" }

# 400 - Invalid email
{ "error": "Invalid email address", "code": "INVALID_EMAIL" }

# 400 - Product not found or unavailable
{ "error": "Product not found or unavailable", "code": "PRODUCT_UNAVAILABLE" }

Step 3 · Payment Flow

After placing an order, the AI Agent should follow these steps:

1
Get Payment Info
Extract usdt_address, total, and usdt_network from the order response
↓
2
Transfer on Chain
Send the exact amount of total USDT (TRC-20) to usdt_address via the TRON network
↓
3
Verify Transaction
Check the transaction via TRONGRID API: https://api.trongrid.io/v1/accounts/{address}/transactions
↓
4
Confirm Payment
Call POST /api.php/orders/{id}/pay to update the order status
↓
5
Final Confirmation
Call GET /api.php/orders/{id} to verify the status changed to paid

Step 4 · Confirm Payment

POST /api.php/orders/{id}/pay

Request

No request body required. The AI Agent should call this endpoint after on-chain verification of the USDT transfer.

Example Request

# Confirm order #42 has been paid
curl -s -X POST api.php/orders/42/pay

Response 200

{
  "order_id": 42,
  "status": "paid",
  "notified": true
}
FieldDescription
statusUpdated status paid
notifiedWhether Telegram notification was sent
Idempotent: Calling this endpoint multiple times on a paid order will not error — it returns the current status.

Step 5 · Query Order

GET /api.php/orders/{id}

Example Request

curl -s api.php/orders/42

Response 200

{
  "order_id": 42,
  "product_name": "Buy Gmail accounts (USA IP | 2FA | PVA)",
  "quantity": 10,
  "unit_price": 1.50,
  "total": 15.00,
  "status": "paid",
  "email": "[email protected]",
  "created_at": "2026-07-02 18:42:00"
}

Status Flow

StatusMeaning
pendingAwaiting payment
paidPaid, awaiting delivery
deliveredDelivered (accounts sent to email)

AI Agent Complete Workflow

1
Browse Products
GET /api.php/products?cat=Gmail&min_price=1&max_price=5&stock_min=1
← Returns product list [{id: 2844, price: 1.50, stock: 342}]
↓
2
AI Agent Decision
Select product ID, quantity, and target email
↓
3
Create Order
POST /api.php/orders
→ {product_id: 2844, quantity: 10, email: "[email protected]"}
← {order_id: 42, total: 15.00, usdt_address: "TNCer...", status: "pending"}
↓
4
On-Chain Transfer
Send exactly 15.00 USDT (TRC-20) to TNCer...
↓
5
Verify & Confirm
Verify via TRONGRID → POST /api.php/orders/42/pay
← {order_id: 42, status: "paid", notified: true}
↓
6
Final Check
GET /api.php/orders/42 → confirm status: "paid"

Notes