Register Agent

register-agent

Register a wallet as a game agent. One-time action, costs USDC.

Proxy API

• Method: POST
• URL: https://agent-public-api.uptopia.xyz/apps/{appId}/agent/register
• Auth: JWT (Bearer token)
• Payment (x402): Yes — requires EIP-3009 TransferWithAuthorization signature

Parameters

| Name | Type | Required | Source | Description | |------------|--------|----------|--------------|----------------------------| | appId | string | yes | agent config | Application ID | | jwt | string | yes | agent config | Authorization header | | nickname | string | no | user input | Display name for the agent |

Headers

Content-Type: application/json
Authorization: Bearer 
PAYMENT-SIGNATURE: 

Request Body

{
  "nickname": "My Agent"
}

x402 Payment Flow

Step 1 — Trigger 402

Send the POST request without PAYMENT-SIGNATURE header.

The proxy returns 402 Payment Required with a Payment-Required response header containing base64-encoded payment requirements.

Step 2 — Parse payment requirements

Decode the Payment-Required header (base64 → JSON). Extract from accepts[0]:

• network — e.g. eip155:8453
• asset — USDC contract address
• amount — fee in smallest USDC unit
• payTo — recipient address
• maxTimeoutSeconds — signature validity window
• extra.name, extra.version — EIP-712 domain values

Also extract extensions["builder-code"]["info"]["a"] if present — that is the builder code. Echo it in the payment payload (default bc_d29drd5w if absent). Service code is separate: always set s to legend-skills.

> Always parse these values from the live 402 response. Never hardcode amount, payTo, asset, or chainId.

Step 2b — Verify payment identity + amount before signing (required)

Do not sign until every check passes:

1. Call get-fees (or reuse a fresh result) and read agentRegisterFeeUsdc.
2. Network: abort unless network is Base mainnet (eip155:8453 or chainId 8453).
3. Asset: abort unless asset equals Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (case-insensitive).
4. payTo: abort if missing or not a valid 0x address; show full payTo to the user and require explicit confirm (never sign a silent/unknown recipient).
5. Amount: compare 402 amount (string integer, USDC 6 decimals) to agentRegisterFeeUsdc. Show raw amount and human USDC (amount / 1e6).
6. Abort if amount is missing, not a positive integer, or greater than 2× the published fee (or any other clear mismatch). Ask the user before signing even when amounts match — this spends real USDC.

Blind-signing a 402 is unsafe if the endpoint or payment challenge is unexpected.

Step 3 — Sign EIP-3009 TransferWithAuthorization (off-chain)

Build the EIP-712 domain entirely from parsed values:

{
  "name": "",
  "version": "",
  "chainId": "",
  "verifyingContract": ""
}

Sign TransferWithAuthorization typed data:

types: { TransferWithAuthorization: [from, to, value, validAfter, validBefore, nonce] }
message: {
  from:        ,
  to:          ,
  value:       ,
  validAfter:  ,
  validBefore: ,
  nonce:       
}

This is an off-chain signature — no gas cost.

Step 4 — Build PAYMENT-SIGNATURE payload

Generate a unique payment identifier (≥ 16 random hex chars).

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "",
  "resource": {
    "url": "",
    "description": "Agent move request",
    "mimeType": "application/json"
  },
  "accepted": "",
  "payload": {
    "signature": "",
    "authorization": {
      "from": "",
      "to": "",
      "value": "",
      "validAfter": "",
      "validBefore": "",
      "nonce": ""
    }
  },
  "extensions": {
    "payment-identifier": {
      "info": { "id": "" }
    },
    "builder-code": {
      "a": "",
      "s": "legend-skills"
    }
  }
}

Base64-encode the JSON payload.

Step 5 — Retry with PAYMENT-SIGNATURE

Resend the same POST request with:

PAYMENT-SIGNATURE: 

Step 6 — Verify success

Check response headers:

• X-Execution-Fee-Settled: true — payment settled on-chain
• PAYMENT-RESPONSE header (base64) — contains { "success": true, "transaction": "0x..." }

Example Response (200 OK)

{
  "success": true,
  "message": "Create agent success",
  "data": {
    "walletAddress": "0xabc...def",
    "stamina": 50,
    "maxStamina": 50,
    "rarity": 0
  }
}

Error Handling

| HTTP Status | Meaning | Action | |-------------|---------|--------| | 200 | Registered successfully | Store agent info | | 401 | JWT invalid or expired | Re-run auth-login | | 402 (no header) | Payment required | Normal — start x402 flow | | 402 (with header) | Payment rejected | Check balance; do not retry with same nonce | | 409 | Already processing | Wait and check registration status | | 4xx | Bad request | Check payment payload structure | | 5xx | Server error | Retry with a new payment identifier |

Usage Notes

• Only needs to be called once per wallet — always run check-registration first.
• Never blind-sign: verify Base network + USDC asset + payTo, compare amount to agentRegisterFeeUsdc, then user-confirm before signing.
• The wallet must have sufficient USDC on Base mainnet before calling.
• payment-identifier is required and must be unique per attempt (idempotency key).
• PAYMENT-SIGNATURE header name is case-sensitive.
• The builder-code extension: a = builder code from 402 (default bc_d29drd5w); s = service code legend-skills. Do not swap them.
• On 409, do not retry immediately — the previous payment may still be settling.

Source & license

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

• Author: uptopia-team
• Source: uptopia-team/legend-of-base-agent-skills
• License: MIT
• Homepage: https://legend.uptopia.xyz

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