Wallets

Manage wallets assigned to trading agents for simulation and live trading.

Endpoints Overview

Method	Endpoint	Description
`GET`	`/api/v1/wallets/agent/:agentId`	List wallets for an agent
`POST`	`/api/v1/wallets/assign`	Assign a wallet to an agent
`POST`	`/api/v1/wallets/:walletAddress/reset`	Reset wallet balances
`POST`	`/api/v1/wallets/:walletAddress/check-deposits`	Check for deposits

All wallet endpoints require JWT authentication.

Wallet Types

Nexgent supports two wallet types:

Type	Description
`simulation`	Virtual wallet for paper trading (sim_* addresses)
`live`	Real Solana wallet for on-chain trading

List Wallets

Get all wallets for an agent and available wallets from environment.

GET /api/v1/wallets/agent/:agentId

Path Parameters

Parameter	Type	Description
`agentId`	UUID	Agent ID

Response

Success (200)

{
  "agentWallets": [
    {
      "walletAddress": "sim_abc123",
      "walletType": "simulation",
      "isAvailable": true,
      "createdAt": "2025-01-20T10:00:00.000Z",
      "updatedAt": "2025-01-20T10:00:00.000Z"
    },
    {
      "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "walletType": "live",
      "isAvailable": true,
      "createdAt": "2025-01-20T10:00:00.000Z",
      "updatedAt": "2025-01-20T10:00:00.000Z"
    }
  ],
  "availableWallets": [
    {
      "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "isAssigned": true
    },
    {
      "walletAddress": "9yLMtg3DX98e08UKTEqcC6kLzheTrB84USnAsgsW",
      "isAssigned": false
    }
  ]
}

Response Fields

agentWallets

Field	Type	Description
`walletAddress`	string	Wallet public key
`walletType`	string	`simulation` or `live`
`isAvailable`	boolean	Whether wallet is loaded from env
`createdAt`	ISO 8601	Assignment time

availableWallets (from environment)

Field	Type	Description
`walletAddress`	string	Wallet public key
`isAssigned`	boolean	Whether assigned to this agent

Example

curl -X GET "https://your-instance.com/api/v1/wallets/agent/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer <access_token>"

Assign Wallet

Assign a wallet to an agent.

POST /api/v1/wallets/assign

Request

{
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "walletType": "live"
}

Field	Type	Required	Description
`agentId`	UUID	Yes	Agent ID
`walletAddress`	string	Yes	Wallet public key
`walletType`	string	Yes	`simulation` or `live`

Validation Rules

Live wallets must be configured in environment variables (WALLET_1, WALLET_2, etc.)
Simulation wallets use sim_* prefix and don't require env configuration
Each agent can have one wallet per type

Response

Success (201)

{
  "success": true,
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "walletType": "live",
  "message": "Wallet assigned successfully"
}

Wallet Not Configured (400)

{
  "error": "Wallet 7xKXt... is not loaded from environment variables. Please configure WALLET_1, WALLET_2, etc."
}

Example

curl -X POST "https://your-instance.com/api/v1/wallets/assign" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "walletType": "live"
  }'

Reset Wallet

Reset a simulation wallet's balances to initial state.

POST /api/v1/wallets/:walletAddress/reset

Path Parameters

Parameter	Type	Description
`walletAddress`	string	Wallet address (sim_* only)

Response

Success (200)

{
  "success": true,
  "message": "Wallet balances reset"
}

⚠️

Reset is only available for simulation wallets. Live wallets cannot be reset.

Check Deposits

Check for new deposits to a wallet and update balances.

POST /api/v1/wallets/:walletAddress/check-deposits

Path Parameters

Parameter	Type	Description
`walletAddress`	string	Wallet public key

Response

Success (200)

{
  "success": true,
  "depositsFound": 2,
  "newBalance": "15.5"
}

Environment Configuration

Live wallets are configured via environment variables:

# .env
WALLET_1=base58_private_key_1
WALLET_2=base58_private_key_2
WALLET_3=base58_private_key_3

⚠️

Security: Private keys should be stored securely. Never commit them to version control.

Related Endpoints

Agents - Manage agents
Agent Balances - View balances
Agent Positions - View positions

Trading Signals Data Sources