Wallet API

The wallet API provides access to the agent's on-chain identity across EVM-compatible chains and Solana. Balance and NFT lookups require API keys (Alchemy for EVM, Helius for Solana) configured via PUT /api/wallet/config.

Endpoints

GET /api/wallet/addresses

Get the agent's EVM and Solana wallet addresses.

Response

{
  "evmAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "solanaAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHU"
}

GET /api/wallet/balances

Get token balances across all supported chains. Requires ALCHEMY_API_KEY for EVM chains and HELIUS_API_KEY for Solana. Returns null for chains where the required API key is not configured.

Response

{
  "evm": {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chains": [
      {
        "chain": "ethereum",
        "chainId": 1,
        "nativeBalance": "1.234",
        "nativeSymbol": "ETH",
        "nativeValueUsd": "3200.00",
        "tokens": [],
        "error": null
      }
    ]
  },
  "solana": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHU",
    "solBalance": "0.5",
    "solValueUsd": "50.00",
    "tokens": []
  }
}

GET /api/wallet/nfts

Get NFTs held by the agent across EVM chains and Solana. Requires ALCHEMY_API_KEY for EVM and HELIUS_API_KEY for Solana.

Response

{
  "evm": [
    {
      "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
      "tokenId": "1234",
      "name": "Bored Ape #1234",
      "imageUrl": "https://..."
    }
  ],
  "solana": {
    "nfts": []
  }
}

GET /api/wallet/config

Get the wallet API key configuration status, RPC provider selections, and current wallet addresses. Key values are not returned — only their set/unset status.

When the cloud wallet feature is enabled (ENABLE_CLOUD_WALLET=1), the response includes additional wallets and primary fields that describe all available wallets (local and cloud) and which source is primary for each chain. The evmAddress and solanaAddress fields reflect whichever wallet is currently primary.

Response

{
  "selectedRpcProviders": {
    "evm": "alchemy",
    "bsc": "alchemy",
    "solana": "helius-birdeye"
  },
  "walletNetwork": "mainnet",
  "legacyCustomChains": [],
  "alchemyKeySet": true,
  "infuraKeySet": false,
  "ankrKeySet": false,
  "nodeRealBscRpcSet": false,
  "quickNodeBscRpcSet": false,
  "managedBscRpcReady": false,
  "cloudManagedAccess": false,
  "heliusKeySet": true,
  "birdeyeKeySet": false,
  "evmChains": ["ethereum", "base"],
  "evmAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "solanaAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHU",
  "walletSource": "local",
  "automationMode": "user-sign-only",
  "pluginEvmLoaded": true,
  "pluginEvmRequired": false,
  "executionReady": true,
  "executionBlockedReason": null,
  "solanaSigningAvailable": true
}

Additional fields when cloud wallet is enabled

When ENABLE_CLOUD_WALLET is active, the response also includes:

{
  "wallets": [
    {
      "source": "local",
      "chain": "evm",
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "provider": "local",
      "primary": false
    },
    {
      "source": "cloud",
      "chain": "evm",
      "address": "0x1234...abcd",
      "provider": "privy",
      "primary": true
    },
    {
      "source": "local",
      "chain": "solana",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHU",
      "provider": "local",
      "primary": true
    }
  ],
  "primary": {
    "evm": "cloud",
    "solana": "local"
  }
}

PUT /api/wallet/config

Update wallet API keys and RPC provider selections. You can set API keys, switch RPC providers per chain, or both in a single request. Setting HELIUS_API_KEY also automatically configures SOLANA_RPC_URL.

When all RPC provider selections are set to "eliza-cloud", the cloud wallet feature flag (ENABLE_CLOUD_WALLET) is automatically enabled.

Request (API keys)

{
  "ALCHEMY_API_KEY": "alchemy-key-here",
  "HELIUS_API_KEY": "helius-key-here"
}

Request (RPC provider selections)

Use the selections field to switch RPC providers for one or more chains. For example, setting a chain to "eliza-cloud" delegates RPC access to Eliza Cloud.

{
  "selections": {
    "evm": "eliza-cloud",
    "bsc": "eliza-cloud",
    "solana": "eliza-cloud"
  }
}

Response

{
  "ok": true
}

POST /api/wallet/import

Import an existing private key for EVM or Solana. Chain is auto-detected if not specified.

Request

{
  "privateKey": "0xabc123...",
  "chain": "evm"
}

Response

{
  "ok": true,
  "chain": "evm",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

POST /api/wallet/generate

Generate one or more new wallets. By default, keys are generated locally and saved to config. When the Steward bridge is configured and source is not "local", wallet generation is delegated to Steward.

Request

{
  "chain": "both",
  "source": "local"
}

Response

{
  "ok": true,
  "wallets": [
    { "chain": "evm", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
    { "chain": "solana", "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHU" }
  ],
  "source": "local"
}

Errors

POST /api/wallet/export

Export private keys in plaintext. Requires explicit confirmation. This action is logged as a security event.

Request

{
  "confirm": true
}

Response

{
  "evm": {
    "privateKey": "0xabc123...",
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  },
  "solana": {
    "privateKey": "base58encodedkey...",
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHU"
  }
}

Steward bridge

The Steward bridge enables delegated transaction signing through an external policy service. When configured, trade and transfer endpoints route signing requests through Steward, which can approve, reject, or hold transactions for policy review before they are broadcast.

GET /api/wallet/steward-status

Get the current status of the Steward bridge connection, including whether the service is configured, reachable, and which agent identity is in use.

Response

{
  "configured": true,
  "available": true,
  "connected": true,
  "baseUrl": "https://steward.example.com",
  "agentId": "agent-1",
  "evmAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "error": null
}

GET /api/wallet/steward-pending-approvals

List transactions awaiting Steward approval.

Response

Returns an array of pending approval objects, each containing the transaction details and the policy that triggered the hold.

POST /api/wallet/steward-approve-tx

Approve a held transaction.

Request body

Response

Returns the approval result with the transaction's new status.

POST /api/wallet/steward-deny-tx

Deny a held transaction.

Request body

Response

Returns the denial result with the transaction's new status.

GET /api/wallet/steward-policies

Get the current Steward policy rules.

Response

Returns an array of policy rule objects that control which transactions require approval.

PUT /api/wallet/steward-policies

Update the Steward policy rules.

Request body

Response

{ "ok": true }

Trading

POST /api/wallet/trade/preflight

Run a preflight check to verify the wallet and RPC are ready for a BSC trade.

Request Body

Response

Returns a readiness object with wallet balance, RPC status, and any blocking issues.

POST /api/wallet/trade/quote

Get a price quote for a BSC token swap before executing.

Request Body

Response

Returns a quote object with estimated output amount, price impact, and route details.

Errors

POST /api/wallet/trade/execute

Execute a token trade on BSC. Behavior depends on wallet configuration, Steward bridge availability, and confirmation:

• Without confirm: true or without a local private key, returns an unsigned transaction for client-side signing.
• With confirm: true, a local key, and appropriate trade permissions, executes the trade on-chain and returns the receipt.
• When the Steward bridge is configured, signing is delegated to the Steward service. Steward may approve the transaction immediately, hold it for policy review, or reject it based on configured policies.

Request headers

Request body

Response (unsigned — user must sign)

Returned when confirm is not true, no local key is available, or the trade permission mode does not allow server-side execution.

{
  "ok": true,
  "side": "buy",
  "mode": "user-sign",
  "quote": {
    "side": "buy",
    "tokenAddress": "0x...",
    "slippageBps": 100,
    "route": "TOKEN/WBNB",
    "routerAddress": "0x...",
    "quoteIn": { "symbol": "BNB", "amount": "0.1", "amountWei": "100000000000000000" },
    "quoteOut": { "symbol": "TOKEN", "amount": "1000", "amountWei": "1000000000000000000000" }
  },
  "executed": false,
  "requiresUserSignature": true,
  "unsignedTx": {
    "to": "0x...",
    "data": "0x...",
    "valueWei": "100000000000000000",
    "chainId": 56
  },
  "requiresApproval": false
}

For sell orders, the response includes an additional unsignedApprovalTx field when the router needs token approval:

{
  "requiresApproval": true,
  "unsignedApprovalTx": {
    "to": "0x...",
    "data": "0x...",
    "valueWei": "0",
    "chainId": 56
  }
}

Response (executed)

Returned when the trade was signed and broadcast (locally or via Steward).

{
  "ok": true,
  "side": "buy",
  "mode": "local",
  "quote": { "..." : "..." },
  "executed": true,
  "requiresUserSignature": false,
  "unsignedTx": { "..." : "..." },
  "requiresApproval": false,
  "execution": {
    "hash": "0x...",
    "nonce": 42,
    "gasLimit": "250000",
    "valueWei": "100000000000000000",
    "explorerUrl": "https://bscscan.com/tx/0x...",
    "blockNumber": null,
    "status": "pending",
    "approvalHash": "0x..."
  }
}

Response (Steward pending approval)

Returned when Steward holds the transaction for policy review instead of signing immediately.

{
  "ok": true,
  "side": "buy",
  "mode": "steward",
  "quote": { "..." : "..." },
  "executed": false,
  "requiresUserSignature": false,
  "unsignedTx": { "..." : "..." },
  "requiresApproval": false,
  "execution": {
    "status": "pending_approval",
    "policyResults": [
      { "policy": "max-trade-value", "result": "pending" }
    ]
  }
}

Response (Steward policy rejection)

Returned with status 403 when Steward rejects the transaction based on policy rules.

{
  "ok": false,
  "mode": "steward",
  "executed": false,
  "requiresUserSignature": false,
  "error": "Policy rejected",
  "execution": {
    "status": "rejected",
    "policyResults": [
      { "policy": "max-trade-value", "result": "denied" }
    ]
  }
}

Errors

GET /api/wallet/trade/tx-status

Check the on-chain status of a previously submitted trade transaction.

Query Parameters

Response

{
  "ok": true,
  "hash": "0x...",
  "status": "success",
  "explorerUrl": "https://bscscan.com/tx/0x...",
  "chainId": 56,
  "blockNumber": 12345678,
  "confirmations": 12,
  "nonce": 42,
  "gasUsed": "150000",
  "effectiveGasPriceWei": "3000000000"
}

Errors

GET /api/wallet/trading/profile

Get a trading profit-and-loss profile from the local trade ledger.

Query Parameters

Response

Returns aggregated trading statistics including realized and unrealized P&L over the requested window.

POST /api/wallet/transfer/execute

Transfer native tokens (BNB) or ERC-20 tokens on BSC.

• Without confirm: true or without a local private key, returns an unsigned transaction for client-side signing.
• With confirm: true and a local key, executes the transfer on-chain.
• When the Steward bridge is configured, signing is delegated to the Steward service with the same policy approval flow as trade execution.

Request headers

Request body

Response (unsigned — user must sign)

{
  "ok": true,
  "mode": "user-sign",
  "executed": false,
  "requiresUserSignature": true,
  "toAddress": "0x...",
  "amount": "1.5",
  "assetSymbol": "BNB",
  "unsignedTx": {
    "chainId": 56,
    "from": "0x...",
    "to": "0x...",
    "data": "0x",
    "valueWei": "1500000000000000000",
    "explorerUrl": "https://bscscan.com",
    "assetSymbol": "BNB",
    "amount": "1.5"
  }
}

For ERC-20 transfers, unsignedTx.to is the token contract address, unsignedTx.data contains the encoded transfer call, and unsignedTx.tokenAddress is included.

Response (executed)

{
  "ok": true,
  "mode": "local",
  "executed": true,
  "requiresUserSignature": false,
  "toAddress": "0x...",
  "amount": "1.5",
  "assetSymbol": "BNB",
  "unsignedTx": { "..." : "..." },
  "execution": {
    "hash": "0x...",
    "nonce": 42,
    "gasLimit": "21000",
    "valueWei": "1500000000000000000",
    "explorerUrl": "https://bscscan.com/tx/0x...",
    "blockNumber": null,
    "status": "pending"
  }
}

Response (Steward pending approval)

{
  "ok": true,
  "mode": "steward",
  "executed": false,
  "requiresUserSignature": false,
  "toAddress": "0x...",
  "amount": "1.5",
  "assetSymbol": "BNB",
  "unsignedTx": { "..." : "..." },
  "execution": {
    "status": "pending_approval",
    "policyResults": [
      { "policy": "max-transfer-value", "result": "pending" }
    ]
  }
}

Response (Steward policy rejection)

Returned with status 403 when Steward rejects the transaction based on policy rules.

{
  "ok": false,
  "mode": "steward",
  "executed": false,
  "requiresUserSignature": false,
  "error": "Policy rejected",
  "execution": {
    "status": "rejected",
    "policyResults": [
      { "policy": "max-transfer-value", "result": "denied" }
    ]
  }
}

Errors

POST /api/wallet/production-defaults

Apply opinionated production defaults for wallet trading configuration (trade permission mode, RPC settings, etc.).

Response

{
  "ok": true,
  "applied": [
    "tradePermissionMode=user-sign-only",
    "bscRpcUrl=https://bsc-dataseed.binance.org"
  ],
  "tradePermissionMode": "user-sign-only"
}

Cloud wallet

These endpoints manage the dual-wallet (local + cloud) architecture. They are gated behind the ENABLE_CLOUD_WALLET feature flag and return 404 when the flag is off.

POST /api/wallet/primary

Set the primary wallet source for a chain. The primary wallet is used for balance lookups, trade execution, and address display. Changing the primary triggers a runtime reload to rebind wallet plugins.

Request

{
  "chain": "evm",
  "source": "cloud"
}

Response

{
  "ok": true,
  "chain": "evm",
  "source": "cloud",
  "restarting": true
}

Errors

POST /api/wallet/refresh-cloud

Re-query Eliza Cloud for the latest cloud wallet descriptors and update the local cache. This re-fetches all chains to pick up upstream address changes such as wallet rotation or migration. If a chain fails to refresh, the previously cached descriptor is preserved.

Changing the primary triggers a runtime reload when wallet bindings have changed.

Request

No request body required.

Response

{
  "ok": true,
  "restarting": true,
  "wallets": {
    "evm": {
      "address": "0x1234...abcd",
      "provider": "privy"
    },
    "solana": {
      "address": "Abc123...xyz",
      "provider": "steward"
    }
  }
}

Errors

Common error codes