Skip to main content

​
What are Agents?

In ActumX, an agent is an entity with its own Solana wallet that can:
  • Hold SOL tokens on Solana devnet
  • Make authenticated API requests
  • Perform autonomous transactions
  • Interact with x402 payment endpoints
Each agent has a unique wallet keypair stored securely in the database.

​
Creating Your First Agent

1

Create an Agent via API

Make a POST request to create a new agent:
curl -X POST http://localhost:3001/v1/agents \
  -H "Content-Type: application/json" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -d '{
    "name": "My First Agent"
  }'
Response:
{
  "agentId": "agent_a1b2c3d4e5f6",
  "name": "My First Agent",
  "publicKey": "5xK8F2JnV...",
  "privateKey": "base64EncodedSecretKey==",
  "balanceSol": 0,
  "balanceLamports": 0,
  "createdAt": "2026-03-03T22:30:00.000Z",
  "warning": "Store this private key now. It is shown only once."
}
Critical: Save the privateKey immediately! It’s only shown once during creation and cannot be retrieved later.
2

Understanding Agent Wallets

When you create an agent, ActumX automatically generates a Solana keypair:From the source code (api/src/modules/agents/service.ts:46-48):
const wallet = Keypair.generate();
const publicKey = wallet.publicKey.toBase58();
const privateKeyBase64 = Buffer.from(wallet.secretKey).toString("base64");
  • Public Key: Used for receiving SOL and identifying the wallet
  • Private Key: Base64-encoded secret key for signing transactions
  • Network: Solana Devnet by default
3

Fund Your Agent on Devnet

Before your agent can make transactions, it needs SOL tokens. Use the devnet faucet endpoint:
curl -X POST http://localhost:3001/v1/agents/agent_a1b2c3d4e5f6/fund-devnet \
  -H "Content-Type: application/json" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -d '{
    "amountSol": 1
  }'
Response:
{
  "agentId": "agent_a1b2c3d4e5f6",
  "network": "solana-devnet",
  "amountSol": 1,
  "signature": "3Xt7K2pQ...",
  "explorerUrl": "https://explorer.solana.com/tx/3Xt7K2pQ...?cluster=devnet",
  "publicKey": "5xK8F2JnV...",
  "balanceSol": 1,
  "balanceLamports": 1000000000
}
The funding process uses Solana’s requestAirdrop method and waits for transaction confirmation (api/src/modules/agents/service.ts:102-111).
4

List Your Agents

Retrieve all agents associated with your account:
curl http://localhost:3001/v1/agents \
  -H "Cookie: YOUR_SESSION_COOKIE"
Response:
{
  "agents": [
    {
      "id": "agent_a1b2c3d4e5f6",
      "name": "My First Agent",
      "publicKey": "5xK8F2JnV...",
      "createdAt": "2026-03-03T22:30:00.000Z",
      "balanceSol": 1,
      "balanceLamports": 1000000000,
      "error": null
    }
  ]
}
The list endpoint automatically fetches current balances from Solana for each agent.

​
Key Implementation Details

​
Agent Creation Flow

From api/src/modules/agents/service.ts:40-75:
  1. Authenticate the user making the request
  2. Generate a new Solana keypair using @solana/web3.js
  3. Create a unique agent ID with prefix agent_
  4. Store the agent in the database with encrypted private key
  5. Return agent details including the private key (only once)

​
Wallet Balance Checking

The system uses SolanaBalanceService to query real-time balances from Solana devnet: 
const balance = await SolanaBalanceService.getBalance(publicKey);
// Returns: { balanceSol, balanceLamports, error }

​
Security Best Practices

  • Private keys are base64-encoded and stored in the database
  • They’re only returned once during agent creation
  • Store private keys securely in your application (e.g., environment variables, secrets manager)
  • Never commit private keys to version control
  • ActumX uses Solana devnet by default
  • Devnet SOL has no real value
  • Before moving to mainnet, audit your security practices
  • Update SOLANA_RPC_URL in .env to switch networks
  • Agents are scoped to user accounts
  • Users can only access their own agents
  • Authentication is verified on every API request

​
Troubleshooting

Error: “failed to fund agent on devnet”Solutions:
  • Solana devnet faucet may be rate-limited
  • Try again after a few minutes
  • Request smaller amounts (0.5 SOL instead of 1 SOL)
  • Check Solana devnet status
Error: “agent not found”Solutions:
  • Verify you’re using the correct agent ID
  • Ensure you’re authenticated as the agent’s owner
  • Check that the agent was successfully created

​
Next Steps

Create API Keys

Generate API keys to authenticate your agent’s requests

Top Up Credits

Add credits to your account for using paid endpoints