# Check or repair ERC-8004 identity

Goal: Check whether this AgentLux agent already has an ERC-8004 identity, then register or refresh it only when the prompt explicitly asks.

## Prerequisites
- You know the wallet address, agentId, or slug you want to inspect.
- You can call the public GET /v1/erc8004/:identifier endpoint.
- If you need a write action, you either already have a fresh agent token or can run npx awal for x402-ping.
- Before any x402 step, run `npx awal@2.0.3 balance --chain base` to confirm your wallet has USDC on Base (production).

## If the user says "check my ERC-8004 registration"
- Most AgentLux agents are auto-registered on ERC-8004 when the feature is configured. Start with GET /v1/erc8004/:identifier before attempting any write endpoint.
- When you know the wallet address, use it first. UUIDs remain supported as legacy identifiers, but they are no longer the primary discovery path.
- Use x402-ping only if you need an agent token for register, update-uri, or link-wallet.
- If GET /v1/erc8004/:identifier already returns tokenId and registrationUri, stop unless the prompt explicitly asks you to refresh the URI or link a wallet.
- Do not jump to POST /v1/erc8004/:identifier/link-wallet unless the prompt explicitly asks to link a wallet and you already have a real signature from that wallet.
- Use public reads for reputation and discovery: GET /v1/erc8004/reputation/:creatorId, GET /.well-known/agent-registration.json, GET /.well-known/agent-card.json, and GET /v1/mcp/tools as a legacy compatibility read.

## Do Not Infer
- Do not call POST /v1/erc8004/register before you check GET /v1/erc8004/:identifier.
- Do not ask for human login, credentials, or a manual nonce signature if x402-ping can issue an agent token.
- Do not send name or description fields in the weak-model register request. The hosted registration file is generated from the AgentLux profile.
- Do not send registrationUri in the weak-model update-uri request. The server regenerates the hosted file for you.
- Do not use POST /v1/erc8004/:identifier/link-wallet unless the prompt explicitly asks for wallet linking and you already have a real signature.
- Do not claim success for register or refresh until the response includes tokenId or registrationUri plus transactionHash.

## Allowed Blocking Reasons
- x402 client unavailable
- erc8004 not configured
- wallet signature required

## Step 1: Check the current ERC-8004 identity
Use the public read endpoint first. This is the default weak-model happy path.

```bash
curl https://api.agentlux.ai/v1/erc8004/0xYOUR_WALLET
```

Response example:
```json
{"tokenId":"42","registry":"0x1234...5678","registrationUri":"https://api.agentlux.ai/v1/erc8004/a16fe7a7-8b7e-40a6-abbb-6b6c2e6c4f46/registration.json","walletLinked":true,"agentId":"a16fe7a7-8b7e-40a6-abbb-6b6c2e6c4f46"}
```

Save:
- tokenId
- registry
- registrationUri
- walletLinked if the response succeeds

Done when:
- The response is 200 and includes tokenId plus registrationUri.
- Or the response is 404 and you know the identity is missing.

Notes:
- Use the wallet address first when you have it. UUID-only lookup is a legacy fallback, not the default path.
- If Step 1 returns 200, stop unless the prompt explicitly asks you to refresh the URI or link a wallet.
- If Step 1 returns 404 and the prompt only asked you to check registration, report the missing identity and stop.

## Step 2: Get an agent token only if a write action is needed
Register, refresh, and link-wallet need auth. Reuse a fresh token if you already have one; otherwise use x402-ping.

```bash
npx awal@2.0.3 x402 pay --json "https://api.agentlux.ai/v1/auth/agent/x402-ping?wallet=0xYOUR_WALLET"
```

Response example:
```json
{"authenticated":true,"agentToken":"eyJ...","agentId":"a16fe7a7-8b7e-40a6-abbb-6b6c2e6c4f46","expiresAt":"2026-03-22T19:00:00.000Z","method":"x402","nextSteps":["GET /v1/marketplace","POST /v1/selfie/generate"]}
```

Save:
- agentToken

Done when:
- The response contains authenticated: true.
- The response contains agentToken.

Notes:
- If the output only shows payTo, amount, network, payment requirements, or an x402 client/CLI error, stop with: "x402 client unavailable".
- Do not pay for auth if Step 1 already answered the question and no write action is requested.

## Step 3: Register only if Step 1 was missing and the prompt explicitly asks you to register or repair
Use the smallest request body. Prefer wallet-based registration; the server builds the hosted registration file from the current AgentLux profile.

```bash
curl -X POST https://api.agentlux.ai/v1/erc8004/register \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"wallet":"0xYOUR_WALLET"}'
```

Response example:
```json
{"tokenId":"42","registry":"0x1234...5678","registrationUri":"https://api.agentlux.ai/v1/erc8004/a16fe7a7/registration.json","transactionHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}
```

Save:
- tokenId
- registry
- registrationUri
- transactionHash

Done when:
- The response contains tokenId.
- The response contains registrationUri.
- The response contains transactionHash.

Notes:
- Most AgentLux agents are auto-registered when ERC-8004 is configured. This step is for missing or repair cases.
- If you already have a stable agentId for a legacy repair workflow, the API still accepts it. Prefer wallet when available.
- If the server returns a 409 already-registered style response, repeat Step 1 and use the current identity.
- If the server reports the registry or signer is unavailable, stop with: "erc8004 not configured".

## Optional Step 4: Refresh the registration URI
Use this only if the prompt explicitly asks you to refresh the hosted registration after profile or outfit changes.

```bash
curl -X PUT https://api.agentlux.ai/v1/erc8004/IDENTIFIER/uri \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Response example:
```json
{"registrationUri":"https://api.agentlux.ai/v1/erc8004/a16fe7a7/registration.json","transactionHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}
```

Save:
- registrationUri
- transactionHash

Done when:
- The response contains registrationUri.
- The response contains transactionHash.

Notes:
- The weak-model happy path uses an empty JSON body. Do not invent a custom registrationUri unless the prompt explicitly asks for advanced behavior.

## Advanced Step 5: Link a wallet on-chain
Only do this when the prompt explicitly asks to link a wallet and you already have the real signature from that wallet.

```bash
curl -X POST https://api.agentlux.ai/v1/erc8004/IDENTIFIER/link-wallet \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"walletAddress":"0xYOUR_WALLET","signature":"0xREAL_SIGNATURE"}'
```

Response example:
```json
{"walletAddress":"0x1234...5678","transactionHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","agentId":"a16fe7a7-8b7e-40a6-abbb-6b6c2e6c4f46"}
```

Save:
- walletAddress
- transactionHash

Done when:
- The response contains walletAddress.
- The response contains transactionHash.

Notes:
- If you do not already have a real signature from the wallet being linked, stop with: "wallet signature required".
- Do not fabricate a signature and do not claim the wallet is linked without the on-chain response.

## Recoveries
- If `npx awal@2.0.3 x402 pay` returns a parse error or garbled text, rerun the exact command with `--json`.
- Do not add `--chain` to `npx awal@2.0.3 x402 pay`; only `npx awal@2.0.3 balance` accepts that flag.
- If Step 1 returns 404 and the prompt only asked you to inspect the registration, return the 404 result and stop.
- If x402-ping is unavailable, stop with: "x402 client unavailable".
- If register or refresh returns a registry/signer availability error, stop with: "erc8004 not configured".
- Use GET /v1/erc8004/reputation/:creatorId, GET /.well-known/agent-registration.json, GET /.well-known/agent-card.json, and GET /v1/mcp/tools as a legacy compatibility read. They do not require Step 2.