Skip to main content

​
Users API

Key Feature: The Users API provides real-time blockchain balance information through a reliable fallback strategy.
The Users API provides endpoints for managing user accounts and accessing wallet balances. These endpoints enable you to check your wallet balance and manage other user-specific data.

​
User and Wallet Model

Best Practice: Store the user’s wallet address securely as it’s used automatically in balance retrieval operations.
Each user in the Mage platform includes:
  1. Identity:
    • Unique user ID (UUID)
    • Name
    • Email
    • Role
    • Organization ID
  2. Authentication:
    • API key
    • OAuth provider
  3. Wallet:
    • Wallet address
    • Associated blockchain network
    • Balance (retrieved in real-time from blockchain)

​
Available Endpoints

Get Wallet Balance

Retrieve the authenticated user’s wallet balance from the blockchain

​
Wallet Operations

Important: The wallet balance endpoint automatically determines the user’s wallet address from their account. No need to provide the address in your requests.
Wallets in Mage have several key characteristics:
  1. Associated with User: Each user has a primary wallet for funding agents
  2. Automatic Agent Wallets: Each agent also automatically gets a dedicated wallet upon creation
  3. Network Specific: Wallets operate on specific blockchain networks (mainnet or testnets)
  4. Balance Reporting: All balances are retrieved in real-time from the blockchain
  5. Fallback Strategy: Balance retrieval follows a priority system - first USDC, then ETH, and finally any other non-zero balance

​
Asset Support

Response Format: All balance values are returned as strings to preserve precision for financial calculations.
The wallet balance endpoint supports multiple cryptocurrencies:
  • USDC: Primary stablecoin for transactions (checked first)
  • ETH: Secondary asset (checked if USDC is unavailable)
  • Other Assets: Additional tokens may be reported if both USDC and ETH balances are zero

​
User Authentication

Required: All wallet balance requests must include your API key in the header to authenticate the user and access their wallet data.
All API requests require authentication using an API key. The key identifies the user and provides access to their data. Your API key should be included in all requests as an HTTP header:
Authentication Error: Requests without a valid API key will receive a 401 error and cannot access wallet data.