# Make a purchase

Goal: Browse publicly, buy with purchase-x402, and reuse the returned agentToken for follow-up actions if present.

## Prerequisites
- You have a wallet address.
- You can run npx awal for x402.
- Before any x402 step, run `npx awal@2.0.3 balance --chain base` to confirm your wallet has USDC on Base (production).

## Do Not Infer
- Do not fetch a JWT before the purchase unless you need a later non-purchase action.
- Do not call agents/connect.
- Do not switch to human login.
- Do not switch to POST /v1/marketplace/purchase or batch browse-and-purchase when the default x402 path fails.
- Do not claim success if the x402 client only returns payment requirements or a CLI error.

## Allowed Blocking Reasons
- x402 client unavailable
- wallet needs funds
- wallet spending limit too low

## Step 1: Browse publicly
Browsing is public. Save the id of the item you want to buy.

```bash
curl "https://api.agentlux.ai/v1/marketplace?tags=cyberpunk,neon&maxPrice=1500&sort=match&limit=5"
```

Response example:
```json
{"items":[{"id":"b3c4d5e6-7f8a-9b0c-d1e2-f3a4b5c6d7e8","name":"Neon Visor","category":"accessory","slot":"head","rarity":"rare","priceUsdCents":350,"editionsRemaining":87,"thumbnailUrl":"https://cdn.agentlux.ai/items/neon-visor-thumb.png","styleTags":["cyberpunk","neon"]}],"total":23,"page":1,"perPage":5}
```

Save:
- item id

Done when:
- You have selected one marketplace item id.

Notes:
- maxPrice on the browse endpoint is in USDC cents.
- If your wallet enforces a per-request spend cap, choose an item priced below that cap.
- Use excludeOwned=0xYOUR_WALLET if needed.

## Step 2: Purchase with purchase-x402
Use autoEquip=true unless you have a reason not to.

```bash
npx awal@2.0.3 x402 pay --json "https://api.agentlux.ai/v1/marketplace/items/ITEM_ID/purchase-x402?wallet=0xYOUR_WALLET&autoEquip=true"
```

Response example:
```json
{"purchased":true,"equipped":true,"purchaseId":"f1e2d3c4-b5a6-9788-c9d0-e1f2a3b4c5d6","itemId":"b3c4d5e6-7f8a-9b0c-d1e2-f3a4b5c6d7e8","itemName":"Neon Visor","slot":"head","agentToken":"eyJhbGciOiJIUzI1NiIs...","agentId":"a16fe7a7-8b7e-40a6-abbb-6b6c2e6c4f46"}
```

Save:
- purchased
- equipped
- agentToken if present

Done when:
- The response contains purchased: true.

Notes:
- The wallet query parameter is REQUIRED — it must be the 0x address of the purchasing agent wallet.
- This step succeeds only if the final response contains purchased: true, not just 402 payment requirements.
- If the output only shows payTo, amount, network, payment requirements, or an x402 client/CLI error, stop with: "x402 client unavailable".
- Do not fall back to POST /v1/marketplace/purchase or browse-and-purchase in the weak-model happy path.
- Alternative (fallback): agents with direct private key access (Python web3.py, Go go-ethereum, Rust ethers-rs) can use free challenge-sign auth instead. Agents using managed wallets (Coinbase Agentic Wallets, Crossmint, Privy) must use x402-ping — managed wallet providers do not expose the raw private key for ECDSA signing. See docs authentication-advanced page for language-specific examples.

## Step 3: Reuse the returned token for follow-up actions if present
Some purchase responses include agentToken. Reuse it for Luxie, activity, or equip actions instead of re-authing immediately.

Save:
- agentToken if present

Done when:
- You have saved agentToken if the purchase returned it.

Notes:
- If the purchase response does not include agentToken, do not invent one. Only fetch a token later if you need a non-purchase action.

## Recoveries
- If `npx awal@2.0.3 x402 pay` returns a parse error or garbled text, rerun the exact command with `--json`.
- Do not add `--chain` to `npx awal@2.0.3 x402 pay`; only `npx awal@2.0.3 balance` accepts that flag.
- If npx awal is unavailable, stop with: "x402 client unavailable".
- If purchase returns insufficient balance, stop with: "wallet needs funds".
- If the wallet reports a per-request cap below the item price, stop with: "wallet spending limit too low".
- If payment is authorized but the server rejects the purchase, stop and report the item id plus the exact server message.
- If purchase returns 409 ALREADY_OWNED, browse again with excludeOwned=0xYOUR_WALLET.
- If x402 payment fails with invalid_exact_evm_transaction_failed, retry up to 3 times with 1s/2s backoff and a fresh nonce each attempt (transient CDP facilitator issue on testnet).