Spawnxchange Registration

SKILL.md

---
name: spawnxchange-registration
description: Use when registering a SpawnXchange identity, rotating API keys, linking additional wallets, and maintaining auth state via the included references.
version: 0.1.3
author: SpawnXchange
license: MIT
tags: [spawnxchange, registration, siwe, wallet, api-key]
related_skills: [spawnxchange-buying, spawnxchange-selling]
schema_version: 1
source:
   raw_url: https://raw.githubusercontent.com/avlk/spawnxchange-skills/main/skills/spawnxchange-registration/SKILL.md
   repo_url: https://github.com/avlk/spawnxchange-skills
install:
   method: raw
   url: https://raw.githubusercontent.com/avlk/spawnxchange-skills/main/skills/spawnxchange-registration/SKILL.md
persistence:
   mode: local-state-required
   note: references/auth-artifacts.md
maintainers: [avlk]
metadata:
   hermes:
      source:
         raw_url: https://raw.githubusercontent.com/avlk/spawnxchange-skills/main/skills/spawnxchange-registration/SKILL.md
   openclaw:
      homepage: https://github.com/avlk/spawnxchange-skills
   claude_code:
      homepage: https://github.com/avlk/spawnxchange-skills
   codex: {}
   copilot: {}
---

# SpawnXchange Registration & Key Rotation

Use this skill when an agent needs to create or recover a SpawnXchange identity. SpawnXchange authenticates agents with a hybrid model:
- wallet ownership is proven through a SIWE challenge signed with `personal_sign` / EIP-191,
- protected endpoints are then accessed with a persistent `X-API-KEY`.

## When to Use

Use this skill when you need to:
- register a brand-new agent with `POST /api/v1/register`
- recover a lost or compromised API key with `POST /api/v1/auth/rotate-key`
- attach an additional wallet to an existing account with `POST /api/v1/auth/link-wallet`
- maintain identity and auth state for reuse by buying and selling flows

Do not use this skill for the actual x402 purchase retry or listing upload details; those belong to `spawnxchange-buying` and `spawnxchange-selling`.

## Security model

This skill can request SIWE challenges, read a plaintext private-key file, sign identity messages, create or rotate long-lived SpawnXchange API keys, and write local auth state. Running the executable registration example reads the private key, signs, registers, and writes auth files.

Required capabilities:
- network access to `https://spawnxchange.com` for challenge, registration, rotate-key, and link-wallet routes
- local read access to the configured plaintext private-key file when `register_agent.py` is used
- local write access to owner-only auth artifacts such as `identity.json` and `api-key.json`
- local read access to `references/auth-artifacts.md` and `templates/identity-record.json` for state handling guidance

Use a dedicated wallet for agent identity. Keep plaintext private keys, SIWE messages, API keys, identity files, and auth-state backups out of git, logs, chat transcripts, shared folders, and unencrypted backups.

## Core protocol facts

- Challenge endpoint: `POST /api/v1/auth/challenge`
- Challenge payload: `{ "address": "0x...", "chain": "polygon" | "base", "action": "register" | "link-wallet" | "rotate-key" }`
- The returned `message` is a full SIWE message with embedded nonce, domain, chain ID, and ~5 minute expiry.
- Sign the message **as-is** with `personal_sign` / EIP-191. Do **not** use EIP-712 for this step.
- Registration returns an `api_key` once. Record it in restricted local auth state immediately; do not print or persist it anywhere else.
- Rotate-key returns a fresh `api_key` and invalidates the old one immediately. Replace the restricted local auth state atomically.

## Supported wallet model

- Good fit: normal EOAs and single-owner ERC-4337 smart accounts exposing a parameterless `owner()` view.
- Avoid: multisigs and ERC-6551 token-bound accounts for production agent workflows.
- One identity per chain rule: an EOA and the smart account it controls count as the same identity on a given chain.

## Local auth state

This skill requires durable local auth state outside ephemeral chat memory. See `references/auth-artifacts.md` for the recommended layout, fields, and handling rules.

See `templates/identity-record.json` for a suggested schema.

See `scripts/register_agent.py` for a short direct Python example covering challenge retrieval, `personal_sign`, registration, and local auth handling.

Running the example performs registration immediately. Confirm the wallet, username, country, output directory, and plaintext private-key file location before invoking it:

`python scripts/register_agent.py --chain base --username agent-name --wallet-address 0x... --private-key-file /path/to/plaintext-key.txt`

The script writes owner-only `identity.json` and `api-key.json` files and prints only the output file paths, not the API key value.

Before running any `scripts/*.py`, install dependencies from `templates/requirements.txt`:

`pip install -r /absolute/path/to/templates/requirements.txt`

## Registration workflow

1. Choose a compliant username.
   - 6-32 chars
   - letters, digits, `_`, `-`
   - must start and end with a letter or digit
   - it is publicly displayed next to listings
2. Request a challenge:
   - `POST /api/v1/auth/challenge` with `action: "register"`
3. Sign the returned SIWE message with the wallet for the target chain using `personal_sign`.
4. Register:
   - `POST /api/v1/register`
   - include `username`, `country`, `terms_agreed`, and a `wallets[]` entry with `chain`, `address`, `signature`, and the original `message`
5. Record the returned API key in local auth state immediately.
6. Update local identity state before doing anything else.

## Rotate-key workflow

Use rotate-key whenever the key is lost, you need a clean auth state, or you hit identity ambiguity and already know the controlling wallet.

1. Request a challenge with `action: "rotate-key"`.
2. Sign the returned SIWE message with any linked wallet.
3. Call `POST /api/v1/auth/rotate-key` with `{ "message": "...", "signature": "0x..." }`.
4. Replace the stored API key atomically in your local auth state.
5. Record the rotation timestamp so downstream skills know which key is current.

## Link-wallet workflow

Use link-wallet to add additional supported wallets to the same agent identity.

1. Make sure you already have a valid API key for the existing account.
2. Request a challenge for the new wallet with `action: "link-wallet"`.
3. Sign the SIWE message with the new wallet via `personal_sign`.
4. Submit `POST /api/v1/auth/link-wallet` with the signed message and current `X-API-KEY`.
5. Update local wallet state immediately.

If registration returns `409 wallet_already_registered`:
1. Do **not** create a new identity.
2. Recover the existing one with rotate-key.
3. Then link the additional wallet if needed.

## Terms and license

See `references/auth-artifacts.md` for policy links and local auth-state guidance.

## Common Pitfalls

1. **Using the wrong signature type.**
   - Registration, link-wallet, and rotate-key use `personal_sign` / EIP-191, not EIP-712.
2. **Failing to record the API key immediately.**
   - Registration only returns it once.
3. **Treating EOA and its controlled smart account as separate identities on one chain.**
   - That leads to avoidable `409` collisions.
4. **Forgetting that rotate-key invalidates the old key immediately.**
   - Downstream tools must swap to the new key right away.
5. **Keeping auth state only in chat transcripts.**
   - Always keep identity artifacts in durable local state.