Reference · Products

Products API

Everything an agent needs to buy goods: register a key, discover products in its human's region, and place an order that settles onchain. All endpoints are under https://api.agcx.org/agent/v1. Selling a service instead? See the Services API.

Authentication

Every endpoint except key registration requires an API key. Send it on either header:

Authorization: Bearer ace_live_…
# or
X-API-Key: ace_live_…

Tip: use X-API-Key for the key so the Authorization header stays free for the MPP payment rail on the order endpoint.

POST/keys

curl -X POST https://api.agcx.org/agent/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'

# 201 Created
{ "apiKey": "ace_live_…" }

The raw key is shown once — store it securely. It cannot be retrieved again.

Browse products

GET/productsAPI key

List, search and filter listings. All parameters are optional.

Param	Type	Description
`q`	string	Free-text search (1–200 chars).
`region`	string	ISO-3166-1 alpha-2 country (e.g. `US`). Returns only listings that ship there, plus worldwide listings.
`maxPrice`	integer	Maximum price in minor units (e.g. `12000` = $120.00).
`categoryId`	uuid	Restrict to one category (see Categories).
`sort`	enum	`newest` (default), `price_asc`, `price_desc`.
`page`	integer	Page number (offset pagination).
`limit`	integer	Results per page, 1–100 (default 20).
`cursor`	uuid	Cursor for keyset pagination — use `nextCursor` from the previous response.

curl "https://api.agcx.org/agent/v1/products?q=keyboard&region=US&sort=price_asc" \
  -H "X-API-Key: $ACE_KEY"

# 200 OK
{
  "listings": [
    {
      "agentSku": "kbd-touch-pbt",
      "title": "LOFREE TOUCH PBT wireless keyboard",
      "priceMinor": 11240,
      "currency": "USD",
      "primaryImageUrl": "https://…",
      "availableQuantity": 8,
      "countryCodes": ["US","CA"],
      "ratingAvg": 4.6,
      "ratingCount": 128
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1,
  "nextCursor": null,
  "sort": "price_asc"
}

countryCodes is the set of ISO countries a listing serves. An empty array means it ships worldwide.

GET/products/:agentSkuAPI key

Fetch a single listing by its agentSku. Returns 404 if it doesn't exist or is hidden.

# 200 OK
{
  "id": "…",
  "agentSku": "kbd-touch-pbt",
  "title": "LOFREE TOUCH PBT wireless keyboard",
  "brand": "LOFREE",
  "primaryImageUrl": "https://…",
  "images": ["https://…"],
  "descriptionHtml": "…",
  "shortDescription": "…",
  "bulletPoints": ["…"],
  "specifications": { "…": "…" },
  "priceMinor": 11240,
  "currency": "USD",
  "availableQuantity": 8,
  "listed": true,
  "countryCodes": ["US","CA"],
  "marketName": "United States",
  "categoryId": "…",
  "categorySlug": "keyboards",
  "categoryName": "Keyboards",
  "storeId": 7,
  "storeName": "Circuit Co",
  "ratingAvg": 4.6,
  "ratingCount": 128,
  "createdAt": "…",
  "updatedAt": "…"
}

Place an order

POST/products/:agentSku/ordersAPI key + payment

Buy a listing. This endpoint is gated by payment: with no payment credential it returns 402 Payment Required carrying both x402 and MPP challenges. Retry with a signed payment to complete. (An equivalent form is POST /orders with agentSku in the body.)

Body

Field	Type	Description
`quantity`	integer	1–1000. Defaults to 1.
`shippingAddress`	object	Requires `line1`, `city`, `postalCode`, `country` (ISO-2). Optional: `name`, `line2`, `region`, `phone`.
`buyerEmail`	string	Contact for the order confirmation.
`buyerName`	string?	Optional buyer name.
`agentWalletAddress`	string	The agent's wallet — used for settlement and refunds.

Paying — x402 or MPP

On the first call with no payment, the exchange replies 402. For x402, retry with the signed payment payload in the X-PAYMENT header. For MPP, present the credential on the Authorization header. Payment is verified synchronously and the funds escrow until the merchant confirms.

curl -X POST https://api.agcx.org/agent/v1/products/kbd-touch-pbt/orders \
  -H "X-API-Key: $ACE_KEY" \
  -H "X-PAYMENT: $X402_PAYLOAD" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 1,
    "agentWalletAddress": "0x8f…2b",
    "buyerEmail": "agent@buyer.xyz",
    "shippingAddress": {
      "line1": "1 Market St", "city": "San Francisco",
      "postalCode": "94103", "country": "US"
    }
  }'

# 201 Created
{
  "agentOrderId": "…",
  "status": "paid",
  "grossMinor": 11240,
  "currency": "USD",
  "payToAddress": "0x…",
  "payment": { "protocol": "x402", "paymentId": "pay_…", "txHash": "0x7a3f…21be" },
  "message": "Payment verified — order placed."
}

Region is enforced here too: if the shippingAddress.country is outside the regions the listing serves, the order is rejected with 422 REGION_NOT_SERVED before any charge.

GET/orders/:idAPI key

Poll an order you placed (scoped to your API key) for its status and fulfilment.

Errors

Status	Meaning
`400`	Invalid query or body (details included).
`401`	Missing or invalid API key.
`402`	Payment required — retry with an x402 or MPP credential.
`404`	Listing or order not found (or hidden).
`422`	`REGION_NOT_SERVED` — the listing doesn't ship to that country.

Prefer to hand the tools straight to an assistant? See the MCP server.