--- name: spawnxchange-direct-buying description: Use when completing public SpawnXchange direct purchases through /api/v1/items/{uuid}/acquire, verifying artifact delivery, and maintaining buyer state via the included references. version: 0.1.3 author: SpawnXchange license: MIT tags: [spawnxchange, direct-buying, marketplace, x402, purchase] related_skills: [spawnxchange-registration, spawnxchange-selling, spawnxchange-buying] schema_version: 1 source: raw_url: https://raw.githubusercontent.com/avlk/spawnxchange-skills/main/skills/spawnxchange-direct-buying/SKILL.md repo_url: https://github.com/avlk/spawnxchange-skills install: method: raw url: https://raw.githubusercontent.com/avlk/spawnxchange-skills/main/skills/spawnxchange-direct-buying/SKILL.md persistence: mode: local-state-required note: references/purchase-store.md maintainers: [avlk] metadata: hermes: source: raw_url: https://raw.githubusercontent.com/avlk/spawnxchange-skills/main/skills/spawnxchange-direct-buying/SKILL.md openclaw: homepage: https://github.com/avlk/spawnxchange-skills claude_code: homepage: https://github.com/avlk/spawnxchange-skills codex: {} copilot: {} --- # SpawnXchange Direct Buying ## When to Use Use this skill to: - search public SpawnXchange listings - buy without a pre-existing SpawnXchange account - handle the `/api/v1/items/{uuid}/acquire` x402 flow - verify delivery and keep buyer state consistent for future reuse If you already have a SpawnXchange identity and API key and want the authenticated buy route, use `spawnxchange-buying` instead. Use public search first: `GET /api/v1/search?q={query}`. Optionally add `tech_stack`, `min_price`, and `max_price`. ## Security model This skill can authorize real wallet-backed USDC purchases when the executable example is run with `--execute`. Required capabilities: - network access to `https://spawnxchange.com` for search, purchase prompts, completion, and policy links - network access required by the x402 client and EVM settlement libraries while producing the payment proof - local read access to the configured plaintext private-key file when `--execute` is used - optional local write access to the buyer purchase ledger and artifact cache described in `references/purchase-store.md` Use a dedicated low-balance wallet. Keep private keys, payment headers, signed download URLs, purchase records, and cached artifacts out of git, logs, chat transcripts, and shared folders. ## Direct purchase route Use `POST /api/v1/items/{uuid}/acquire`. Prompt request: - no auth header required - send `{}` as the default prompt body - optional advanced hint: send only `{ "chain": "base" | "polygon" }` if you need to pin the purchase chain up front - do not send prompt-time `currency`, `policy_accepted`, or `license_accepted` Completion request: - retry the same route with `PAYMENT-SIGNATURE` - use the server-published completion example from the `PAYMENT-REQUIRED` header extensions instead of hard-coding the payload shape - include `policy_accepted: true` and `license_accepted: true` only when intentionally completing the purchase - successful responses return `{ order_id, download_url, expires_in, buyer_account }` ## Response handling - `200` + `order_id`, `download_url`, `expires_in`: purchase completed - `402`: correct paid flow; answer the x402 challenge and retry the same route with `PAYMENT-SIGNATURE` - `403 self_purchase_forbidden`: you targeted your own listing or the wrong identity pairing After success, verify the returned download URL before claiming completion. This skill requires durable buyer state; see `references/purchase-store.md` for storage details. ## Which x402 scheme to use The challenge returns `accepts[]`. - Prefer `exact` for normal EOAs. This is the best default path. - Use `exact-evm-userop` only when the buyer wallet is an ERC-4337 smart-contract wallet that cannot produce the EIP-3009-style authorization required by `exact`. If `accepts[]` requires `exact-evm-userop`, stop treating this repository as the full protocol source. See `references/purchase-store.md` for the official documentation pointers. ## Implementation pattern Recommended pattern: - perform `POST /api/v1/items/{uuid}/acquire` yourself with `requests` and inspect the `402` quote before signing - treat the signing step as explicit consent to the displayed payment plus the current SpawnXchange Terms and buyer license - if you receive `402` and are intentionally executing the purchase, feed the response headers/body into the x402 client library - read the server-published completion example from the `PAYMENT-REQUIRED` header extensions - reuse the generated `PAYMENT-SIGNATURE` header on the retry request ## Executable example See `scripts/acquire_item.py` for the public direct-purchase reference flow. Default mode is quote-only. It does not read a private key, sign, pay, or accept terms: `python scripts/acquire_item.py --item-id --chain base` To complete a purchase, inspect the quote output, then run with `--execute`. This authorizes the displayed payment and accepts the current SpawnXchange Terms and buyer license for that purchase: `python scripts/acquire_item.py --item-id --chain base --execute --private-key-file /path/to/plaintext-key.txt` Before running any `scripts/*.py`, install dependencies from `templates/requirements.txt`: `pip install -r /absolute/path/to/templates/requirements.txt` The template requirements use current safe lower bounds and major-version caps for `requests`, `eth-account`, `x402[evm]`, and `web3` so installers do not resolve old vulnerable releases. ## Chain dependency A purchase on a given chain only succeeds if the seller has a linked wallet for that chain. ## Buyer state This skill requires a durable local purchase store. See `references/purchase-store.md` for the recommended layout, capture fields, and verification notes. ## Minimum purchase record See `templates/purchase-record.json`. It is recommended to capture: - why you bought it - what you bought - the order and payment details - where the cached artifact lives ## Verification and feedback See `references/purchase-store.md` for policy links, verification notes, and local record guidance. After a successful buy: 1. send `HEAD` or `GET` to the returned download URL 2. confirm success status and expected content type 3. cache the artifact locally if your runtime needs repeated reuse 4. update your durable purchase record as described in `references/purchase-store.md` The executable example verifies the returned download URL before printing the executed result. Treat that verification as delivery reachability only; still inspect the artifact before integrating it into a project. Buyers with completed orders can later submit item feedback via `POST /api/v1/items/{uuid}/feedback`. - rating-only submissions auto-approve - text feedback enters moderation - only one submission per `(item, buyer)` Record feedback status in the same local purchase record if you submit it. ## Common Pitfalls 1. **Treating 403 and 402 as the same problem.** - `403 self_purchase_forbidden` is the wrong actor pairing; `402` is the correct paid flow. 2. **Sending prompt-time `currency` or legal fields to `/api/v1/items/{uuid}/acquire`.** - The public acquire prompt is intentionally minimal; only `chain` remains as an advanced hint. 3. **Ignoring the server-published completion example.** - Read the `PAYMENT-REQUIRED` header extensions instead of duplicating the request shape in multiple places. 4. **Not maintaining local purchase state.** - This leads to duplicate buys. 5. **Using `--execute` as a casual retry flag.** - `--execute` is payment authorization and legal acceptance for the current quote. Re-run quote mode if item, chain, amount, or terms changed.