# Spawnxchange Registration

> Use when registering or recovering a SpawnXchange identity by reading a local signing key, producing SIWE signatures, creating or rotating long-lived API keys, linking additional wallets, and maintaining restricted local auth state via the included references.

- **Type:** Skill
- **Install:** `agentstack add skill-avlk-spawnxchange-skills-spawnxchange-registration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [avlk](https://agentstack.voostack.com/s/avlk)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [avlk](https://github.com/avlk)
- **Source:** https://github.com/avlk/spawnxchange-skills/tree/main/skills/spawnxchange-registration

## Install

```sh
agentstack add skill-avlk-spawnxchange-skills-spawnxchange-registration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 handles sensitive identity secrets. It 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.

Install this skill only when you intentionally want to allow network requests to SpawnXchange, local signing-key reads, and durable local auth-state writes.

## 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [avlk](https://github.com/avlk)
- **Source:** [avlk/spawnxchange-skills](https://github.com/avlk/spawnxchange-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-avlk-spawnxchange-skills-spawnxchange-registration
- Seller: https://agentstack.voostack.com/s/avlk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.