How it works

Sections

Overview

AgentMall lets AI agents buy products from 11 retailers with a single API call.

CLI

npx agentmall

API Example

$ curl -X POST https://api.agentmall.sh/api/purchases \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "product_url": "https://amazon.com/dp/B0DDQJLVJW",
      "quantity": 1
    }],
    "delivery_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "phone_number": "+14155550100",
      "country": "US"
    },
    "max_budget": 5000,
    "buyer_email": "jane@example.com"
  }'

What happens

Initial request returns 402 status. Agent pays in USDC on Tempo, then retries with receipt.

01Agent looks up product with GET /api/products?url=... to get price, variants, and suggested budget.

02Agent confirms product, price, and budget with the user before proceeding.

03Agent POSTs order with product URL, delivery address, email, and max_budget.

04API returns 402. Agent pays max_budget + $1.50 in USDC on Tempo, then retries with receipt.

05Order submitted. Status updates sent to buyer email. Processing takes 5–10 minutes.

06Refund issued automatically if actual total (product + tax + shipping) is lower than max_budget, or if the order fails.

Required fields

itemsarrayrequiredProducts to order. Each item needs a product_url and quantity.

delivery_addressobjectrequiredUS shipping address with name, street, city, state, zip, phone, country.

max_budgetintegerrequiredPrice ceiling in cents. Use suggestedMaxBudget from product lookup. $1.50 service fee added on top.

buyer_emailstringrequiredEmail for order notifications (placed, shipped, delivered, failed).

Optional fields

idempotency_keystringUUID to prevent duplicate orders. Safe for retries.

metadataobjectArbitrary key-value data attached to the purchase.

variantarraySize, color, or other variant selections as [{label, value}].

Product costUp to max_budget (in cents)

Service fee$1.50 per order

Total MPP chargemax_budget + $1.50

Refunds are issued automatically if the actual total (product + tax + shipping) is lower than max_budget, or if the order fails entirely. Refunds are sent as USDC to the original payer wallet.

payment_receivedsubmittedpendingorderedfailed

AmazonWalmartTargetBest BuyHome DepoteBayLowe'sWayfairAce Hardware1-800 FlowersPokemon Center

All products must be from a single retailer per order. US shipping addresses only.

budget_exceededCheckout price exceeded max_budget. Place a new order with higher budget.

out_of_stockProduct is unavailable. Try again later or choose alternative.

product_not_foundProduct page doesn't exist or URL is invalid.

product_unavailableProduct exists but can't be purchased.

invalid_urlURL is not from a supported retailer.

variant_requiredProduct requires variant selection (size, color). Use GET /api/products to see options.

variant_unavailableSelected variant is not available.

quantity_unavailableRequested quantity not available.

quantity_limitRetailer limits the quantity (typically 1–20 units).

invalid_addressShipping address failed validation. Check state code and ZIP.

shipping_unavailableRetailer cannot ship to this address.

retailer_unavailableRetailer is temporarily down. Retry in a few minutes.

unsupported_retailerRetailer is not in the supported list.

budget_exceededThe actual total exceeded your maximum budget. A refund is issued automatically.

order_failedGeneric checkout failure. A refund is issued automatically.

cancelledOrder was cancelled. Full charge refunded.

What currencies are supported?USDC on the Tempo network. Payment is handled automatically via MPP.

Do I need an API key?No. Purchases are authenticated via MPP payment, and successful purchase responses include a buyer_token for checking that order and its refund later.

Can I check prices before ordering?Yes. Use GET /api/products?url=<product_url> to get the current price, discount info, variants, and a suggested max_budget before placing an order.

Can I order from multiple retailers?Not in a single order. All items must be from the same retailer. Submit separate orders for different retailers.

What countries are supported?US shipping addresses only.

How long does processing take?Orders typically process in 5–10 minutes. Wait at least 5 minutes before checking status, then poll every 1–2 minutes.

What happens if the product is cheaper than max_budget?The difference between max_budget and the actual total (product + tax + shipping) is automatically refunded to your wallet after the order completes.

What about Prime or promotional pricing?Displayed prices may reflect Prime or promo pricing that won’t apply at checkout. The suggested max_budget uses the current extracted price or selected variant price, plus a 15% tax/price buffer and an $8 shipping buffer.

Can I cancel an order?Not through our API. Once submitted, cancellation depends on the retailer.

How do refunds work?Refunds are automatic. Overpayments and failed orders are refunded in USDC to the original payer wallet. Track refund status with npx agentmall refund <id>, or pass --buyer-token <amtk_...> if the order was placed elsewhere. You can also use the refund status API with the buyer_token returned at purchase time.

Can I use shortened URLs?No. Short links like a.co or bit.ly will fail. Use the full product page URL (e.g. amazon.com/dp/...).

↑↓

Scroll

123456

Go to sections

ENTERESC

Actions

Twitter(X)