Moralis Wallets API

openapi: 3.0.0
info:
  title: EVM Balance Wallets API
  version: '2.2'
servers:
- url: https://deep-index.moralis.io/api/v2.2
security:
- ApiKeyAuth: []
tags:
- name: Wallets
paths:
  /wallets/{address}/approvals:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get ERC20 approvals by wallet
      description: List active ERC20 token approvals for a wallet, showing which contracts have access.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletApprovals
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: query
        name: limit
        description: The desired page size of the result.
        required: false
        schema:
          type: integer
          minimum: 0
      - in: query
        name: cursor
        description: The cursor returned in the previous response (used for getting the next page).
        schema:
          type: string
      - in: path
        name: address
        description: The wallet address from which to retrieve active ERC20 token approvals
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      responses:
        '200':
          description: Returns active ERC20 token approvals for the specified wallet address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletApprovals'
      x-mcp-prompt: Enter the wallet address to view its active ERC20 token approvals. Use this when users want to check a wallet’s token approvals or review security settings.
  /wallets/{address}/history:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get the complete decoded transaction history of a wallet
      description: Get the complete decoded transaction history for a given wallet. All transactions are parsed, decoded, categorized and summarized into human-readable records.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletHistory
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: query
        name: from_block
        description: 'The minimum block number from which to get the transactions

          * Provide the param ''from_block'' or ''from_date''

          * If ''from_date'' and ''from_block'' are provided, ''from_block'' will be used.

          '
        required: false
        schema:
          type: integer
          minimum: 0
      - in: query
        name: to_block
        description: 'The maximum block number from which to get the transactions.

          * Provide the param ''to_block'' or ''to_date''

          * If ''to_date'' and ''to_block'' are provided, ''to_block'' will be used.

          '
        required: false
        schema:
          type: integer
          minimum: 0
      - in: query
        name: from_date
        description: 'The start date from which to get the transactions (format in seconds or datestring accepted by momentjs)

          * Provide the param ''from_block'' or ''from_date''

          * If ''from_date'' and ''from_block'' are provided, ''from_block'' will be used.

          '
        required: false
        schema:
          type: string
      - in: query
        name: to_date
        description: 'Get the transactions up to this date (format in seconds or datestring accepted by momentjs)

          * Provide the param ''to_block'' or ''to_date''

          * If ''to_date'' and ''to_block'' are provided, ''to_block'' will be used.

          '
        schema:
          type: string
      - in: path
        name: address
        description: The address of the wallet
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      - in: query
        name: include_internal_transactions
        description: If the result should contain the internal transactions.
        required: false
        schema:
          type: boolean
      - in: query
        name: nft_metadata
        description: If the result should contain the nft metadata.
        required: false
        schema:
          type: boolean
      - in: query
        name: cursor
        description: The cursor returned in the previous response (used for getting the next page).
        schema:
          type: string
      - in: query
        name: order
        description: The order of the result, in ascending (ASC) or descending (DESC)
        required: false
        schema:
          $ref: '#/components/schemas/orderList'
      - in: query
        name: limit
        description: The desired page size of the result.
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Returns wallet history of a wallet address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletHistory'
      x-mcp-prompt: Provide the wallet address to retrieve its complete history. Use this when users request a wallet’s full transaction log or want a detailed activity overview.
  /wallets/{address}/tokens:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get token balances with prices by wallet address
      description: Fetch ERC20 and native token balances for a given wallet address, including their USD prices. Each token returned includes on-chain metadata, as well as off-chain metadata, logos, spam status and more. Additional options to exclude spam tokens, low-liquidity tokens and inactive tokens.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletTokenBalancesPrice
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: The address from which token balances will be checked
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      - in: query
        name: to_block
        description: The block number up to which the balances will be checked.
        required: false
        schema:
          type: number
      - in: query
        name: token_addresses
        description: The addresses to get balances for (optional)
        required: false
        schema:
          type: array
          maxItems: 10
          items:
            type: string
      - in: query
        name: exclude_spam
        description: Exclude spam tokens from the result
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: exclude_unverified_contracts
        description: Exclude unverified contracts from the result
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: cursor
        description: The cursor returned in the previous response (used for getting the next page).
        schema:
          type: string
      - in: query
        name: limit
        description: The desired page size of the result.
        required: false
        schema:
          type: integer
          minimum: 0
      - in: query
        name: exclude_native
        description: Exclude native balance from the result
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: max_token_inactivity
        description: Exclude tokens inactive for more than the given amount of days
        required: false
        schema:
          type: number
      - in: query
        name: min_pair_side_liquidity_usd
        description: Exclude tokens with liquidity less than the specified amount in USD. This parameter refers to the liquidity on a single side of the pair.
        required: false
        schema:
          type: number
      responses:
        '200':
          description: Returns token balances with prices for a specific address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/erc20TokenBalanceWithPriceResult'
      x-mcp-prompt: Enter the wallet address to view its ERC20 token balances and prices. Use this when users want a wallet’s token holdings with USD values or are assessing portfolio value.
  /wallets/{address}/net-worth:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get wallet net worth
      description: Calculate the total net worth of a wallet in USD, with options to exclude spam tokens for accuracy. Options to query cross-chain using the `chains` parameter, as well as additional options to exclude spam tokens, low-liquidity tokens and inactive tokens.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletNetWorth
      parameters:
      - in: query
        name: chains
        description: The chains to query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: The wallet address
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      - in: query
        name: exclude_spam
        description: Exclude spam tokens from the result
        required: false
        schema:
          type: boolean
          default: false
          example: true
      - in: query
        name: exclude_unverified_contracts
        description: Exclude unverified contracts from the result
        required: false
        schema:
          type: boolean
          default: false
          example: true
      - in: query
        name: max_token_inactivity
        description: Exclude tokens inactive for more than the given amount of days
        required: false
        schema:
          type: number
          example: 1
      - in: query
        name: min_pair_side_liquidity_usd
        description: Exclude tokens with liquidity less than the specified amount in USD. This parameter refers to the liquidity on a single side of the pair.
        required: false
        schema:
          type: number
          example: 1000
      responses:
        '200':
          description: Returns the net worth of a wallet in USD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/netWorthResult'
      x-mcp-prompt: Provide the wallet address to calculate its net worth. Specify if spam tokens should be excluded. Use this when users ask for a wallet’s total value or want a portfolio valuation.
  /wallets/{address}/defi/summary:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get the DeFi summary of a wallet
      description: Summarize a wallet’s DeFi activity, including total USD value, unclaimed rewards and active protocols.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getDefiSummary
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: Wallet address
        required: true
        schema:
          type: string
          example: '0xd100d8b69c5ae23d6aa30c6c3874bf47539b95fd'
      responses:
        '200':
          description: Returns the defi summary for the wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletDefiSummary'
      x-mcp-prompt: Enter the wallet address to view its DeFi summary. Use this when users want an overview of a wallet’s DeFi activity or are exploring DeFi investments.
  /wallets/{address}/defi/{protocol}/positions:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get detailed DeFi positions by protocol for a wallet
      description: Fetch detailed DeFi positions for a given wallet and protocol.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getDefiPositionsByProtocol
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: Wallet address
        required: true
        schema:
          type: string
          example: '0xd100d8b69c5ae23d6aa30c6c3874bf47539b95fd'
      - in: path
        name: protocol
        description: The protocol to query
        required: true
        schema:
          $ref: '#/components/schemas/defiProtocolList'
          example: aave-v3
      responses:
        '200':
          description: Returns the defi positions by protocol for the wallet address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  protocol_name:
                    type: string
                    description: The name of the protocol
                    example: Uniswap v2
                  protocol_id:
                    type: string
                    description: The id of the protocol
                    example: uniswap-v2
                  protocol_url:
                    type: string
                    description: The url of the protocol
                    example: https://app.uniswap.org/pools/v2
                  protocol_logo:
                    type: string
                    description: The logo of the protocol
                    example: https://cdn.moralis.io/defi/uniswap.png
                  total_usd_value:
                    type: number
                    example: 47754.14278954011
                  total_unclaimed_usd_value:
                    type: number
                    nullable: true
                    example: null
                  positions:
                    type: array
                    items:
                      $ref: '#/components/schemas/defiProtocolPosition'
      x-mcp-prompt: Provide the wallet address and protocol to view its DeFi positions. Use this when users ask for specific DeFi protocol activity or need detailed position data.
  /wallets/{address}/defi/positions:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get DeFi positions of a wallet
      description: Get a concise overview of a wallet’s DeFi positions across all protocols.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getDefiPositionsSummary
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: Wallet address
        required: true
        schema:
          type: string
          example: '0xd100d8b69c5ae23d6aa30c6c3874bf47539b95fd'
      responses:
        '200':
          description: Returns all defi positions for the wallet address.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/defiPositionSummaryResponse'
      x-mcp-prompt: Enter the wallet address to retrieve its DeFi positions summary. Use this when users want a quick summary of a wallet’s DeFi holdings or are comparing protocols.
  /wallets/{address}/chains:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get active chains by wallet address
      description: List the blockchain networks a wallet is active on, including their first and last seen timestamps. Options to query cross-chain using the `chains` parameter.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletActiveChains
      parameters:
      - in: path
        name: address
        description: Wallet address
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      - in: query
        name: chains
        description: The chains to query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/chainList'
      responses:
        '200':
          description: Returns the active chains for the wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletActiveChains'
      x-mcp-prompt: Provide the wallet address to see its active chains. Use this when users ask which blockchains a wallet uses or want to analyze cross-chain activity.
  /wallets/{address}/stats:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get summary stats by wallet address
      description: Retrieve key statistics for a wallet, such as total transaction count and activity.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletStats
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: Wallet address
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      responses:
        '200':
          description: Returns the stats for the wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletStat'
      x-mcp-prompt: Enter the wallet address to fetch its stats. Use this when users want a wallet’s activity metrics or are analyzing its usage patterns.
  /wallets/{address}/profitability/summary:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get profit and loss summary by wallet address
      description: Get a profit and loss summary for a given wallet, over a specified timeframe (`days`).
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletProfitabilitySummary
      parameters:
      - in: path
        name: address
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
        description: The wallet address for which profitability summary is to be retrieved.
      - in: query
        name: days
        required: false
        schema:
          type: string
        description: Timeframe in days for the profitability summary. Options include 'all', '7', '30', '60', '90' default is 'all'.
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      responses:
        '200':
          description: Successful response with the profitability summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count_of_trades:
                    type: number
                    description: Total count of trades executed by the wallet.
                  total_trade_volume:
                    type: string
                    description: Total trade volume managed by the wallet.
                  total_realized_profit_usd:
                    type: string
                    description: Total realized profit in USD for the wallet.
                  total_realized_profit_percentage:
                    type: number
                    description: Total realized profit as a percentage.
                  total_buys:
                    type: number
                    description: Total number of buy transactions.
                  total_sells:
                    type: number
                    description: Total number of sell transactions.
                  total_sold_volume_usd:
                    type: string
                    description: Total USD volume of tokens sold by the wallet.
                  total_bought_volume_usd:
                    type: string
                    description: Total USD volume of tokens bought by the wallet.
      x-mcp-prompt: Provide the wallet address and a timeframe in `days`. Use this when users ask for a wallet’s profit and loss overview.
  /wallets/{address}/profitability:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get detailed profit and loss by wallet address
      description: Get a detailed profit and loss breakdown by token for a given wallet, over a specified timeframe (`days`). Optionally filter by `token_addresses` for specific tokens.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletProfitability
      parameters:
      - in: path
        name: address
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
        description: The wallet address for which profitability is to be retrieved.
      - in: query
        name: days
        required: false
        schema:
          type: string
        description: Timeframe in days for which profitability is calculated, Options include 'all', '7', '30', '60', '90' default is 'all'.
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: query
        name: token_addresses
        description: The token addresses list to filter the result with
        required: false
        schema:
          type: array
          maxItems: 25
          items:
            type: string
      responses:
        '200':
          description: Successful response with profitability data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletProfitabilityResponse'
      x-mcp-prompt: Enter the wallet address and optional token addresses to analyze profitability. Use this when users want detailed profit data for a wallet or are evaluating specific token performance.
  /wallets/{address}/swaps:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get swap transactions by wallet address
      description: List all swap transactions (buy/sell) for a specific wallet. Optionally filter by `tokenAddress` for specific token swaps.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getSwapsByWalletAddress
      parameters:
      - in: query
        name: chain
        description: The chain to query
        required: false
        schema:
          $ref: '#/components/schemas/chainList'
      - in: path
        name: address
        description: The wallet address token-transactions are to be retrieved for.
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      - in: query
        name: tokenAddress
        description: The token address to get transaction for (optional)
        required: false
        schema:
          type: string
      - in: query
        name: cursor
        description: The cursor returned in the previous response (used for getting the next page).
        schema:
          type: string
      - in: query
        name: limit
        description: The desired page size of the result.
        required: false
        schema:
          type: integer
          minimum: 0
      - in: query
        name: fromBlock
        description: 'The minimum block number from which to get the token transactions

          * Provide the param ''from_block'' or ''from_date''

          * If ''from_date'' and ''from_block'' are provided, ''from_block'' will be used.

          '
        required: false
        schema:
          type: integer
          minimum: 0
      - in: query
        name: toBlock
        description: The block number to get the token transactions from
        required: false
        schema:
          type: string
      - in: query
        name: fromDate
        description: 'The start date from which to get the token transactions (format in seconds or datestring accepted by momentjs)

          * Provide the param ''from_block'' or ''from_date''

          * If ''from_date'' and ''from_block'' are provided, ''from_block'' will be used.

          '
        required: false
        schema:
          type: string
      - in: query
        name: toDate
        description: 'The end date from which to get the token transactions (format in seconds or datestring accepted by momentjs)

          * Provide the param ''to_block'' or ''to_date''

          * If ''to_date'' and ''to_block'' are provided, ''to_block'' will be used.

          '
        required: false
        schema:
          type: string
      - in: query
        name: order
        description: The order of the result, in ascending (ASC) or descending (DESC)
        required: false
        schema:
          $ref: '#/components/schemas/orderList'
      - name: transactionTypes
        in: query
        required: false
        schema:
          type: string
        description: Array of transaction types. Allowed values are 'buy', 'sell'.
      responses:
        '200':
          description: Returns swap transactions by wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getSwapsByWalletAddressResponse'
      x-mcp-prompt: Provide the wallet address to view its swap transactions. Use this when users want to track a wallet's swap activity or analyze its trading behavior.
  /wallets/{address}/insight:
    get:
      security:
      - ApiKeyAuth: []
      summary: Get wallet insight metrics
      description: Retrieve comprehensive wallet insight metrics including activity age, transfer counts, counterparties, and swap volume.
      tags:
      - Wallets
      x-tag-sdk: wallets
      operationId: getWalletInsight
      parameters:
      - in: path
        name: address
        description: The wallet address to get insight for
        required: true
        schema:
          type: string
          example: '0xcB1C1FdE09f811B294172696404e88E658659905'
      - in: query
        name: chains
        description: The chains to query. If not provided, aggregates across all supported chains.
        required: false
        schema:
          type: array
          items:
            type: string
          example:
          - '0x1'
          - '0x89'
      - in: query
        name: includeChainBreakdown
        description: When true, includes a per-chain breakdown array in the response with both native and USD values.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Returns wallet insight metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletInsightResponse'
      x-mcp-prompt: Provide the wallet address to get comprehensive insight metrics. Use this when users want to analyze wallet behavior, activity patterns, or counterparty relationships.
components:
  schemas:
    erc20TokenBalanceWithPrice:
      type: object
      required:
      - name
      - symbol
      - decimals
      - balance
      - possible_spam
      - usd_price
      - usd_price_24hr_percent_change
      - usd_price_24hr_usd_change
      - use_value_24hr_usd_change
      - usd_value
      - portfolio_percentage
      - balance_formatted
      - native_token
      properties:
        token_address:
          type: string
          description: The address of the token contract
        name:
          type: string
          description: The name of the token
        symbol:
          type: string
          description: The symbol of the token
        logo:
          type: string
          description: The logo of the token
        thumbnail:
          type: string
          description: The thumbnail of the token logo
        decimals:
          type: integer
          description: The number of decimals on the token
        balance:
          type: string
          description: The balance of the token
        possible_spam:
          type: boolean
          description: Indicates if a contract is possibly a spam contract
        verified_contract:
          type: boolean
          description: Indicates if a contract is verified
        usd_price:
          type: string
          description: USD price of the token
        usd_price_24hr_percent_change:
          type: string
          description: 24-hour percent change in USD price of the token
        usd_price_24hr_usd_change:
          type: string
          description: 24-hour change in USD price of the token
        usd_value_24hr_usd_change:
          type: string
          description: 24-hour change in USD value of the token based on the balance
        usd_value:
          type: number
          description: USD value of the token balance
        portfolio_percentage:
          type: number
          description: Percentage of the token in the entire portfolio
        balance_formatted:
          type: string
          description: Balance of the token in decimal format
        native_token:
          type: boolean
          description: Indicates if the token is a native coin
        total_supply:
          type: string
          description: Total supply of the token
        total_supply_formatted:
          type: string
          description: Total supply of the token in decimal format
        percentage_relative_to_total_supply:
          type: number
          description: Percentage of the token in the total supply
    decodedEvent:
      type: object
      properties:
        signature:
          type: string
          example: Transfer(address,address,uint256)
        label:
          type: string
          example: Transfer
        type:
          type: string
          example: event
        params:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: from
              value:
                type: string
                example: '0x26C5011483Add49801eA8E3Ee354fE013895aCe5'
              type:
                type: string
                example: address
    native_transfer:
      required:
      - from_address
      - value
      - value_formatted
      - internal_transaction
      - token_symbol
      - token_logo
      properties:
        from_address_entity:
          type: string
          description: The from address entity
          example: Opensea
        from_address_entity_logo:
          type: string
          description: The logo of the from address entity
          example: https://opensea.io/favicon.ico
        from_address:
          type: string
          description: The address that sent the NFT
          example: '0x057Ec652A4F150f7FF94f089A38008f49a0DF88e'
        from_address_label:
          type: string
          nullable: true
          description: The label of the from address
          example: Binance 1
        to_address_entity:
          type: string
          description: The to address entity
          example: Beaver Build
        to_address_entity_logo:
          type: string
          description: The logo of the to address entity
          example: https://beaverbuild.com/favicon.ico
        to_address:
          type: string
          description: The address that received the NFT
          example: '0x057Ec652A4F150f7FF94f089A38008f49a0DF88e'
        to_address_label:
          type: string
          nullable: true
          description: The label of the to address
          example: Binance 2
        value:
          type: string
          description: The value that was sent in the transaction (ETH/BNB/etc..)
          example: '1000000000000000'
        value_formatted:
          type: string
          description: The value that was sent in the transaction (ETH/BNB/etc..) in decimal format
          example: '0.1'
        direction:
          type: string
          description: The direction of the transfer
          example: outgoing
        internal_transaction:
 

# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moralis/refs/heads/main/openapi/moralis-wallets-api-openapi.yml