ClawHub

Spawnxchange Registration

Data & APIs

Use when registering a SpawnXchange identity, rotating API keys, linking additional wallets, and maintaining auth state via the included references.

Install

openclaw skills install spawnxchange-registration

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.

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 local auth state immediately.
  • Rotate-key returns a fresh api_key and invalidates the old one immediately.

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.

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.
More in Data & APIs