API Documentation

Wallets API

Create and manage crypto wallets for AI agents and users.

Create Wallet

Create a new wallet for an agent or user.

bash

POST /api/wallets/create

Request Body

Parameter	Type	Description
ownerId	string	ID of the agent or user who will own the wallet
type	string	Wallet type (agent or user)
currencies	string[]	Array of supported currencies (ETH, USDC, DAI)

Example Request

json

{
  "ownerId": "agent_abc123",
  "type": "agent",
  "currencies": ["ETH", "USDC"]
}

Example Response

json

{
  "success": true,
  "data": {
    "walletId": "wal_abc123xyz789",
    "address": "0x...",
    "ownerId": "agent_abc123",
    "type": "agent",
    "currencies": ["ETH", "USDC"],
    "createdAt": "2024-03-20T12:00:00Z"
  }
}

Get Wallet

Retrieve details of a specific wallet.

bash

GET /api/wallets/:walletId

Parameters

Parameter	Type	Description
walletId	string	Unique identifier of the wallet

Example Response

json

{
  "success": true,
  "data": {
    "walletId": "wal_abc123xyz789",
    "address": "0x...",
    "ownerId": "agent_abc123",
    "type": "agent",
    "currencies": ["ETH", "USDC"],
    "balances": {
      "ETH": "1.5",
      "USDC": "1000.00"
    },
    "createdAt": "2024-03-20T12:00:00Z"
  }
}

List Wallets

Retrieve a list of wallets with optional filtering.

bash

GET /api/wallets

Query Parameters

Parameter	Type	Description
ownerId	string?	Filter by owner ID
type	string?	Filter by wallet type (agent or user)
currency	string?	Filter by supported currency
page	number?	Page number for pagination (default: 1)
limit	number?	Number of items per page (default: 20, max: 100)

Example Response

json

{
  "success": true,
  "data": {
    "items": [
      {
        "walletId": "wal_abc123xyz789",
        "address": "0x...",
        "ownerId": "agent_abc123",
        "type": "agent",
        "currencies": ["ETH", "USDC"],
        "balances": {
          "ETH": "1.5",
          "USDC": "1000.00"
        },
        "createdAt": "2024-03-20T12:00:00Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

Get Wallet Balance

Retrieve the balance of a specific currency in a wallet.

bash

GET /api/wallets/:walletId/balance/:currency

Parameters

Parameter	Type	Description
walletId	string	Unique identifier of the wallet
currency	string	Currency code (ETH, USDC, DAI)

Example Response

json

{
  "success": true,
  "data": {
    "walletId": "wal_abc123xyz789",
    "currency": "ETH",
    "balance": "1.5",
    "updatedAt": "2024-03-20T12:00:00Z"
  }
}

Wallet Webhooks

Subscribe to wallet events using webhooks to receive real-time updates.

To receive webhook notifications, you need to register a webhook endpoint in your developer settings.

Event Types

Event	Description
wallet.created	Triggered when a new wallet is created
wallet.balance.updated	Triggered when a wallet's balance changes
wallet.currency.added	Triggered when a new currency is added to a wallet

Example Webhook Payload

json

{
  "event": "wallet.balance.updated",
  "data": {
    "walletId": "wal_abc123xyz789",
    "address": "0x...",
    "currency": "ETH",
    "balance": "1.5",
    "previousBalance": "1.0",
    "updatedAt": "2024-03-20T12:00:00Z"
  }
}