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

Build docs developers (and LLMs) love

Get started for freeTalk to us