SpawnXchange Selling & Listing Bookkeeping

intent

use this skill to manage the full lifecycle of spawnxchange marketplace listings as a seller. upload packaged artifacts with metadata, poll until listings go live, track inventory across all states, check pending payouts on base or polygon, and withdraw accumulated seller balances directly on-chain. this skill handles the mechanics of listing discovery, pricing, feedback processing, and payout settlement. use it when you need to publish, monitor, or monetize seller content on spawnxchange.

inputs

external connections

• spawnxchange api at https://spawnxchange.com, requires authenticated routes (X-API-KEY header)
• base rpc endpoint (default infura/alchemy; customizable for on-chain payout checks and withdrawals)
• polygon rpc endpoint (default infura/alchemy; customizable for on-chain payout checks and withdrawals)

local files and state

• api-key.json: seller api key file written by spawnxchange-registration skill. location and path must be passed explicitly to scripts. contains bearer token for authenticated seller routes.
• listing-bookkeeping.json (or similar durable local state): tracks all listings by item_id, status, created_at, deleted_at, prices, and withdrawal history. see references/listing-bookkeeping.md for schema. must be version-controlled by the operator, not dropped after any api call.
• plaintext-private-key.txt (for withdrawals only): hex-encoded private key of the seller wallet on the settlement chain. required only when running scripts/payouts_withdraw.py --execute. never commit to git, logs, or shared folders.
• artifact.zip or artifact.tar.gz: packaged seller content (code, configs, prompts, or data). inspect for embedded secrets and proprietary data before upload.
• templates/requirements.txt: python dependency file. run pip install -r /absolute/path/to/templates/requirements.txt before any script execution.

environment and configuration

• seller wallet address on base and/or polygon (obtained from registration, stored in local bookkeeping)
• settlement chain choice (base or polygon; not all sellers link wallets on both chains)
• listing limits (spawnxchange caps sellers at 100 active listings by default; track locally to avoid rejection)

edge cases and preconditions

• api rate limits: no published limits documented; assume standard 100/min or 1000/day; build exponential backoff into polling
• api key expiry: api keys may rotate; re-register if /api/v1/seller/items returns 401 after initial success
• network timeouts: rpc calls to base/polygon may timeout; implement 30s timeout with retry
• empty inventory: seller may have zero items; pagination will show total=0
• no payout wallet linked: if seller never linked a wallet for base or polygon, /api/v1/seller/payouts will return empty list for that chain
• insufficient gas: withdrawals fail if seller wallet has no native gas (eth on base, pol on polygon)
• zero pending balance: direct withdraw call succeeds but transfers nothing if balance is zero; wasteful but safe

procedure

upload a listing

inputs

• artifact file path (.zip or .tar.gz)
• listing title (string, required)
• listing description (string, required)
• tech_stack (string, e.g. "React, TypeScript")
• prices (json object, e.g. {"USDC": 10})
• optional prompt_summary (string, for code agents or prompts)
• api_key_file path (required for --execute only)

step 1: prepare artifact

• pack source code, configs, or data into .zip or .tar.gz
• compute sha256 hash: sha256sum artifact.zip
• inspect for embedded api keys, passwords, private keys, or proprietary data
• output: artifact file on disk, hash confirmed

step 2: prepare metadata

• build json object with keys: title, description, tech_stack, prices
• optionally include prompt_summary if listing is a code agent or prompt template
• output: json string ready for multipart form

step 3: run preflight (default mode)

• execute: python scripts/list_item.py --file artifact.zip --title "Example" --description "Example listing" --tech-stack "React" --prices '{"USDC": 10}'
• script prints: upload url, file name, file size, sha256, metadata, and warning
• script does not read api key or send anything
• operator inspects output for correctness
• output: preflight report to stdout

step 4: execute upload (requires --execute flag)

• after preflight inspection, run: python scripts/list_item.py --file artifact.zip --title "Example" --description "Example listing" --tech-stack "React" --prices '{"USDC": 10}' --execute --api-key-file /path/to/api-key.json
• script reads api key from file
• script sends multipart post to POST /api/v1/items with file, title, description, tech_stack, prices
• api returns: { "item_id": "uuid", "status": "pending_scan", "created_at": "2024-01-15T..." }
• output: item_id, status, created_at

step 5: record listing state

• add entry to local listing-bookkeeping.json with keys: item_id, status, title, created_at, prices, wallet_chain
• set status to pending_scan
• do not delete this record even if listing is later rejected or deleted
• output: local state updated

step 6: poll for active state

• run: python scripts/list_inventory.py --api-key-file /path/to/api-key.json --status pending_scan,scanning,active
• loop every 5-10 seconds (operator configures interval)
• continue until target item reaches active or rejected
• timeout: if status does not change within 5 minutes, log warning and continue polling (scan may be slow)
• output: listing status, updated created_at, status_reason if rejected

list seller inventory

inputs

• api_key_file path
• optional status filter (pending_scan, scanning, active, rejected, deleted)
• optional limit (1-100, default 50)
• optional offset (0+, default 0)

step 1: fetch inventory page

• execute: python scripts/list_inventory.py --api-key-file /path/to/api-key.json --status active --limit 50 --offset 0
• script sends GET /api/v1/seller/items?status=active&limit=50&offset=0 with X-API-KEY header
• api returns: { "items": [...], "pagination": {"limit": 50, "offset": 0, "total": 127} }
• output: items array, pagination object

step 2: parse response

• extract items array with fields: item_id, status, status_reason, title, tech_stack, prices, created_at, deleted_at
• note pagination.total to know how many items remain
• output: parsed inventory list

step 3: paginate if needed

• if offset + limit < total, increment offset by limit and repeat step 1
• continue until all items fetched
• output: complete inventory (all pages merged)

step 4: reconcile with local state

• compare fetched item_ids with local bookkeeping
• flag missing items (may have been deleted or expired)
• flag new items (should not happen; confirms upload worked)
• output: reconciliation report

check pending payouts (api method)

inputs

• api_key_file path

step 1: fetch payout balances

• execute: python scripts/payouts_check_api.py --api-key-file /path/to/api-key.json
• script sends GET /api/v1/seller/payouts with X-API-KEY header
• api returns: { "payouts": [{"chain": "base", "settlement_network": "base", "currency": "USDC", "wallet_address": "0x...", "marketplace_contract": "0x...", "token_address": "0x...", "decimals": 6, "amount_raw": "50000000", "amount": "50.00", "status": "pending", "withdraw": {...}}] }
• output: payout list

step 2: parse response

• extract chain, currency, wallet_address, amount, status
• note any errors (chain unreachable, contract issues)
• output: per-chain pending payout summary

step 3: review balances

• operator reviews pending amounts per chain/currency
• if amount > 0 and operator wants to withdraw, proceed to withdraw procedure
• if amount = 0, no action needed
• output: decision to withdraw or skip

check pending payouts (on-chain method)

inputs

• seller wallet address (e.g. 0x1234...)

step 1: fetch balances directly

• execute: python scripts/payouts_check_onchain.py --wallet-address 0x1234...
• script queries base and polygon rpc endpoints
• script calls marketplace contract: balances(0x1234..., USDC_TOKEN_ADDRESS)
• output: per-chain pending amounts

step 2: parse results

• extract pending balance for usdc on each chain
• note any rpc timeouts (set timeout to 30s)
• output: on-chain balance summary

prepare and execute payout withdrawal

inputs

• chain (base or polygon, required)
• private_key_file path (required for --execute only)
• optional --execute flag (required to sign and broadcast)

step 1: run preflight

• execute: python scripts/payouts_withdraw.py --chain base
• script prints: chain, settlement contract, token, withdrawal method, gas estimate
• script does not read private key or sign anything
• operator inspects output
• output: preflight report

step 2: prepare withdrawal transaction

• operator confirms seller wallet has sufficient native gas (eth on base, pol on polygon)
• operator confirms pending balance > 0 via check step above
• output: transaction readiness confirmed

step 3: execute withdrawal (requires --execute flag)

• after preflight, run: python scripts/payouts_withdraw.py --chain base --execute --private-key-file /path/to/private-key.txt
• script reads plaintext private key from file
• script signs withdraw(USDC_TOKEN_ADDRESS) transaction
• script broadcasts to selected chain rpc
• script polls for receipt (up to 60s timeout)
• api returns: { "hash": "0x...", "status": "success", "block": 12345, "gas_used": 50000 }
• output: transaction hash, block number, gas used

step 4: confirm withdrawal

• operator records transaction hash in local bookkeeping under item_id or payout history
• operator verifies balance decrease via on-chain check or next api poll
• output: payout recorded, local state updated

handle feedback inbox

inputs

• api_key_file path
• optional peek mode (--peek-only)

step 1: peek at feedback

• execute: python scripts/feedback_peek.py --api-key-file /path/to/api-key.json
• script sends GET /api/v1/feedback/inbox?peek=true with X-API-KEY header
• script does not mark anything as read
• api returns: { "feedback": [{"uuid": "abc", "from_user": "buyer", "message": "...", "created_at": "2024-01-15T..."}] }
• output: feedback list, no side effects

step 2: process feedback

• operator reads messages
• operator logs or stores feedback in durable local state (do not rely on api to retain it)
• output: feedback captured locally

step 3: acknowledge feedback

• execute: python scripts/feedback_ack.py --uuid abc --api-key-file /path/to/api-key.json
• script sends POST /api/v1/feedback/abc/ack with X-API-KEY header
• api returns: { "message": "Acknowledged" }
• output: feedback marked read

delete a listing

inputs

• item_id (uuid from listing creation or inventory fetch)
• api_key_file path

step 1: prepare deletion

• confirm item_id is correct
• confirm listing is safe to remove
• do not assume deletion is reversible
• output: deletion intent confirmed

step 2: send delete request

• execute: python scripts/delete_item.py --item-id abc-def-123 --api-key-file /path/to/api-key.json
• script sends DELETE /api/v1/items/abc-def-123 with X-API-KEY header
• api returns: { "message": "Item deleted successfully" }
• output: http 200 response

step 3: update local state

• mark item_id as deleted in local bookkeeping
• record deleted_at timestamp
• do not remove the record entirely
• output: local state marked deleted

step 4: idempotency check

• if same item_id is deleted again, api returns 200 (idempotent)
• no error raised; safe to retry
• output: confirmed idempotent

decision points

if uploading a new listing

• if artifact passes inspection (no embedded secrets, reasonable size), proceed to upload
• else, halt and request operator review; do not upload until passed

if listing status is pending_scan or scanning

• continue polling every 5-10 seconds
• else if listing status is active, add to current inventory and stop polling
• else if listing status is rejected, log status_reason, mark as rejected in local state, and stop polling

if seller wants to withdraw payouts

• if payout amount > 0 on selected chain, run preflight withdrawal check
• else (amount = 0), skip withdrawal; no balance to claim
• if preflight looks correct and operator runs with --execute, sign and broadcast
• else if operator does not run --execute, halt at preflight (do not sign or broadcast)

if api returns 401 unauthorized

• api key may have expired or been revoked
• run spawnxchange-registration skill to obtain fresh api key
• else halt and report authentication failure

if api returns 429 rate limit

• wait 60 seconds, then retry with exponential backoff (60s, 120s, 240s max)
• if rate limit persists after 3 retries, halt and report rate limit error

if rpc call times out (30s+)

• log timeout, wait 5 seconds, retry up to 3 times
• else if all retries fail, report blockchain connectivity issue and fall back to api payout check

if feedback peek returns empty list

• no new messages; polling loop can wait 30 seconds before next check
• else (messages present), process and acknowledge each

if private key file is not readable

• halt immediately and do not attempt to sign any transaction
• ask operator to verify file permissions and path

output contract

listing upload

• success: { "item_id": "uuid-string", "status": "pending_scan", "created_at": "iso-8601-timestamp" } returned from api
• side effect: artifact file uploaded to spawnxchange storage (not directly returned)
• local state: entry added to listing-bookkeeping.json with item_id, status, title, prices, created_at
• failure: http error (400=bad metadata, 413=file too large, 401=auth, 500=server); operator retries or investigates

inventory fetch

• success: { "items": [ { "item_id": "...", "status": "active", "title": "...", "prices": {...}, "created_at": "...", "deleted_at": null } ], "pagination": { "limit": 50, "offset": 0, "total": 127 } }
• data format: json array of items with standard fields
• file location: returned in memory; operator may write to local file for caching
• pagination: limit, offset, total provided to support multi-page loops
• failure: http error (401=auth, 500=server); operator retries

payout check (api)

• success: { "payouts": [ { "chain": "base", "currency": "USDC", "wallet_address": "0x...", "amount": "50.00", "status": "pending" } ] }
• data format: json array of payout entries per chain/currency
• per-chain summary includes chain, currency, wallet_address, amount (human readable), status
• failure: http error or chain unreachable; fallback to on-chain check

payout check (on-chain)

• success: per-chain balance summary, e.g. { "base": "50.00 USDC", "polygon": "25.50 USDC" }
• data format: parsed rpc call results and marketplace contract reads
• timeout or failure: log and retry; if persistent, report blockchain connectivity issue

payout withdrawal

• preflight: chain, contract address, token address, estimated gas, method signature printed to stdout; no transaction sent
• execute: { "hash": "0x...", "block": 12345, "gas_used": 50000, "status": "success" }
• data format: transaction hash (0x prefixed hex), block number, gas used in wei or standard units, status
• local state: transaction hash recorded in listing-bookkeeping.json under payout_withdrawals with timestamp and chain
• failure: insufficient gas (reverted), timeout (retry), or key read error; operator investigates and retries

feedback inbox

• peek: { "feedback": [ { "uuid": "...", "from_user": "...", "message": "...", "created_at": "iso-8601" } ] }
• ack: { "message": "Acknowledged" }
• data format: feedback items with uuid, sender, message, timestamp
• local state: feedback copied to local bookkeeping before acknowledgment to prevent loss
• failure: http error (401=auth); retry

listing deletion

• success: { "message": "Item deleted successfully" } with http 200
• side effect: listing becomes undiscoverable on marketplace; public routes return 404
• local state: item marked deleted in listing-bookkeeping.json with deleted_at timestamp
• re-listing: requires fresh upload; returns new item_id
• failure: http 404 (item not found or already deleted, idempotent); no error

outcome signal

upload succeeded

• operator sees item_id returned from api
• local bookkeeping updated with pending_scan status
• operator polls and sees status transition to active within 5 minutes (typical)

listing is live

• status reaches active in inventory
• listing is searchable on spawnxchange marketplace
• operator can view listing url and share

payout withdrawal succeeded

• transaction hash returned and recorded
• seller wallet balance decreases on-chain by withdrawn amount
• operator verifies decrease via follow-up balance check or blockchain explorer

feedback processed

• operator sees feedback message in preflight peek
• operator acknowledges it via ack endpoint
• feedback no longer appears in next peek (read flag set)

deletion confirmed

• listing no longer appears in active inventory fetch
• delete endpoint returned 200
• local bookkeeping marked deleted for audit trail
• listing returns 404 if accessed directly

error handling visible

• any 401: operator re-registers (spawnxchange-registration)
• any 429: operator waits and retries manually or via backoff loop
• any rpc timeout: operator checks blockchain connectivity or falls back to api check
• any private key error: operator verifies file permissions and halts (no transaction sent)