Auth Login

auth-login

Sign a login message with the agent's private key and obtain an access token (JWT) from the gateway API.

Gateway API

• Method: POST
• URL: https://agent-api.uptopia.xyz/api/v1/auth/validate
• Auth: None (this endpoint issues tokens)
• Payment (x402): No

Parameters

| Name | Type | Required | Source | Description | |--------------|--------|----------|--------------|--------------------------------| | privateKey | string | yes | agent config | Wallet private key for signing |

Flow

Step 1 — Generate nonce and message

Generate a cryptographically random nonce (≥ 8 bytes, base64url-encoded) and build the sign-in message:

Hello from Base! Please sign this message to verify your wallet.

Nonce: 

Step 2 — Sign with EIP-191 (personal_sign)

Sign the message using wallet.signMessage(message) with the private key from .env.

Step 3 — POST to validate endpoint

POST https://agent-api.uptopia.xyz/api/v1/auth/validate
Content-Type: application/json

{
  "address": "",
  "message": "",
  "signature": "",
  "nonce": ""
}

Example Response (200 OK)

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "wallet": "0xabc...def",
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "fid": 12345,
      "username": "player.base",
      "displayName": "Player Base",
      "pfpUrl": "https://example.com/avatar.png"
    },
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

Error Handling

| HTTP Status | Meaning | Action | |-------------|---------|--------| | 200 | Token issued | Store data.accessToken | | 401 | Invalid signature or nonce | Regenerate nonce and retry | | Other | Unexpected error | Do not retry automatically |

Usage Notes

• The accessToken is used as Authorization: Bearer for all authenticated skills.
• On 401, re-run auth-login for a full login. Ignore or store refreshToken only if you have a separate refresh flow; this pack has no refresh skill.
• Address must be sent in lowercase.
• Nonce must be unique per request — never reuse.
• Never log or display the full access token; truncate when showing to users.

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.