Wallet Management

The wallet system provides a smart contract-based wallet (account abstraction) for managing your digital assets. This guide covers how to create, retrieve, and manage your wallet, as well as how to view your portfolio and transaction history.

Overview

Your wallet is a smart contract account that provides enhanced security and functionality compared to traditional externally-owned accounts. The wallet system supports:

  • Account Abstraction - Smart contract-based wallet addresses
  • Portfolio Tracking - View all your token balances and their USD/BRL values
  • Transaction History - Track all your wallet transactions
  • Liquidity Pool Positions - Monitor your Uniswap V3 positions

Prerequisites

Before using wallet endpoints, ensure you have:

  • Completed authentication and have a valid access token
  • Completed KYC verification (may be required for certain operations)

Get Wallet

Retrieve your wallet address. If you don't have a wallet yet, this will return null.

Get wallet address

curl -X GET https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response (Wallet exists):

{
  "status": 200,
  "message": "Wallet retrieved successfully",
  "data": {
    "wallet": "0x1234567890123456789012345678901234567890"
  }
}

Response (No wallet):

{
  "status": 200,
  "message": "Wallet not found",
  "data": {
    "wallet": null
  }
}

Create Wallet

Create a new smart contract wallet for your account. If a wallet already exists, this endpoint will return the existing wallet address.

Create wallet

curl -X POST https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Wallet created successfully",
  "data": {
    "wallet": "0x1234567890123456789012345678901234567890"
  }
}

Response (Wallet already exists):

{
  "status": 200,
  "message": "Wallet already exists",
  "data": {
    "wallet": "0x1234567890123456789012345678901234567890"
  }
}

Note: The wallet creation process uses account abstraction technology. The wallet address is deterministic and will be the same if you call this endpoint multiple times.

Get Transaction History

Retrieve your wallet's transaction history. The history is cached for 10 minutes for performance.

Get transaction history

curl -X GET https://api.example.com/api/wallet/history \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "History retrieved successfully",
  "data": {
    "transactions": [
      {
        "id": "transaction-id",
        "hash": "0xabcdef...",
        "from": "0x1234...",
        "to": "0x5678...",
        "value": "1000000000000000000",
        "timestamp": "2024-01-01T00:00:00.000Z",
        "status": "SUCCESS",
        "type": "TRANSFER"
      }
    ],
    "nextLastId": "last-transaction-id"
  }
}

Response Fields:

  • transactions - Array of transaction objects
  • nextLastId - ID of the last transaction (for pagination)

Note: The history endpoint returns the last 10 transactions by default. Results are cached for 10 minutes.

Get Portfolio

Retrieve your complete portfolio including all token balances with their current USD and BRL values. The portfolio is cached for 1 minute.

Get portfolio

curl -X GET https://api.example.com/api/wallet/portfolio \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Portfolio retrieved successfully",
  "data": {
    "tokens": [
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "chain": {
          "id": 137,
          "name": "Polygon"
        },
        "decimals": 6,
        "price": {
          "usd": 1.0,
          "brl": 5.0,
          "usd_24h_change": 0.0,
          "brl_24h_change": 0.0
        },
        "balance": {
          "token": "1000000000",
          "formatted": "1000.0",
          "usd": 1000.0,
          "brl": 5000.0
        },
        "underlyingTokenAddress": "0x..."
      }
    ]
  }
}

Response Fields:

  • tokens - Array of token objects, sorted by USD value (highest first)
  • Each token includes:
    • symbol - Token symbol (e.g., "USDC", "ETH")
    • name - Token full name
    • address - Token contract address
    • chain - Blockchain information (id and name)
    • decimals - Token decimals
    • price - Current price in USD and BRL, with 24h change
    • balance - Token balance (raw, formatted, USD value, BRL value)
    • underlyingTokenAddress - Address of underlying token (for wrapped/staked tokens)

Note: Only tokens with a balance greater than 0 are included in the portfolio. The portfolio is cached for 1 minute to improve performance.

Get Liquidity Pool Positions

Retrieve your Uniswap V3 liquidity pool positions. This endpoint shows all your active positions in Uniswap V3 pools on Polygon.

Get liquidity pool positions

curl -X GET https://api.example.com/api/wallet/liquidity-pool-positions \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Liquidity pool positions retrieved successfully",
  "data": {
    "positions": [
      {
        "tokenId": "12345",
        "token0": {
          "symbol": "USDC",
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "decimals": 6,
          "amount": "1000.0",
          "price": {
            "usd": 1.0,
            "brl": 5.0,
            "usd_24h_change": 0.0,
            "brl_24h_change": 0.0
          }
        },
        "token1": {
          "symbol": "ETH",
          "address": "0x7ceb23fd6fc0adc59cf2b2c9c0c0c0c0c0c0c0c0",
          "decimals": 18,
          "amount": "1.0",
          "price": {
            "usd": 2000.0,
            "brl": 10000.0,
            "usd_24h_change": 2.5,
            "brl_24h_change": 2.5
          }
        },
        "fee": 3000,
        "tickLower": -100,
        "tickUpper": 100,
        "liquidity": "1000000000000000000"
      }
    ]
  }
}

Response Fields:

  • positions - Array of Uniswap V3 position objects
  • Each position includes:
    • tokenId - NFT token ID representing the position
    • token0 - First token in the pair (with amount and price)
    • token1 - Second token in the pair (with amount and price)
    • fee - Pool fee tier (e.g., 3000 = 0.3%)
    • tickLower - Lower tick of the position
    • tickUpper - Upper tick of the position
    • liquidity - Current liquidity amount

Note: Positions are cached for 10 minutes. Only positions on Polygon (chain ID 137) are currently supported.

Wallet Address Format

Wallet addresses are Ethereum-compatible addresses (42 characters starting with 0x). These are smart contract addresses that provide account abstraction capabilities.

Example: 0x1234567890123456789012345678901234567890

Caching

The API uses caching to improve performance:

  • Portfolio: Cached for 1 minute
  • History: Cached for 10 minutes
  • Liquidity Pool Positions: Cached for 10 minutes

Cache invalidation happens automatically when new transactions occur or when you make changes to your wallet.

Error Handling

Wallet Not Found

{
  "status": 404,
  "message": "Wallet not found"
}

This error occurs when trying to access wallet features (history, portfolio, positions) before creating a wallet.

Client Not Found

{
  "status": 404,
  "message": "Client not found"
}

This error occurs when the authenticated client doesn't exist in the system.

Error Creating Wallet

{
  "status": 500,
  "message": "Error creating wallet"
}

This error occurs when there's an issue with the wallet creation process.

Complete Flow Example

Here's a complete example of the wallet management flow:

# 1. Check if wallet exists
curl -X GET https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 2. Create wallet if it doesn't exist
curl -X POST https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Get portfolio
curl -X GET https://api.example.com/api/wallet/portfolio \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 4. Get transaction history
curl -X GET https://api.example.com/api/wallet/history \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 5. Get liquidity pool positions
curl -X GET https://api.example.com/api/wallet/liquidity-pool-positions \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Important Notes

  1. Account Abstraction: Your wallet uses smart contract technology (account abstraction), which provides enhanced security and functionality compared to traditional wallets.

  2. Deterministic Address: Your wallet address is deterministic based on your account. Calling create wallet multiple times will return the same address.

  3. Supported Chains: Currently, wallets are created on Polygon (chain ID 137). Portfolio and positions are tracked on Polygon.

  4. Token Support: The portfolio endpoint supports all tokens configured in the system, including wrapped tokens and staked tokens (aTokens).

  5. Price Updates: Token prices are fetched from external price oracles and cached. Prices include both USD and BRL values with 24-hour change percentages.

  6. Transaction History: The history endpoint shows transactions from your smart contract wallet. It includes transfers, swaps, and other on-chain activities.

  7. Liquidity Positions: Only Uniswap V3 positions on Polygon are currently tracked. Each position is represented as an NFT (Non-Fungible Token).

Was this page helpful?