# Register Agent

> A Claude skill from uptopia-team/legend-of-base-agent-skills.

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

## Install

```sh
agentstack add skill-uptopia-team-legend-of-base-agent-skills-register-agent
```

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

## About

# 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

```json
{
  "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:

```json
{
  "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).

```json
{
  "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)

```json
{
  "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](https://github.com/uptopia-team)
- **Source:** [uptopia-team/legend-of-base-agent-skills](https://github.com/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.

## 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-uptopia-team-legend-of-base-agent-skills-register-agent
- Seller: https://agentstack.voostack.com/s/uptopia-team
- 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%.