Skip to main content

​
Agents API

Manage agents within your tenant. Each agent gets encrypted EVM and Solana wallets on creation.

​
Create Agent

Creates an agent with encrypted wallet keypairs. 
POST /agents
Auth: Tenant API key Request Body: 
{
  id: string;        // Unique agent ID (1-128 alphanumeric, _ - . :)
  name: string;      // Display name
  platformId?: string; // Optional external platform ID
}
Response: 
{
  "ok": true,
  "data": {
    "id": "my-agent",
    "name": "My Trading Agent",
    "tenantId": "your-tenant",
    "walletAddresses": {
      "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
      "solana": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    },
    "createdAt": "2026-03-26T12:00:00.000Z"
  }
}

const agent = await steward.createWallet("my-agent", "My Trading Agent");

​
List Agents

Returns all agents for the authenticated tenant. 
GET /agents
Auth: Tenant API key Response: 
{
  "ok": true,
  "data": [
    {
      "id": "my-agent",
      "name": "My Trading Agent",
      "tenantId": "your-tenant",
      "walletAddresses": { "evm": "0x742d...", "solana": "7xKXtg..." },
      "createdAt": "2026-03-26T12:00:00.000Z"
    }
  ]
}

const agents = await steward.listAgents();

​
Get Agent

Returns a single agent by ID. 
GET /agents/:agentId
Auth: Tenant API key or agent JWT 
const agent = await steward.getAgent("my-agent");

​
Delete Agent

Permanently deletes an agent and all associated data (wallets, policies, transactions). 
DELETE /agents/:agentId
Auth: Tenant API key (agent tokens cannot delete) Response: 
{
  "ok": true,
  "data": { "deleted": "my-agent" }
}
This cascades: encrypted keys, wallet entries, policies, transactions, and approval queue items are all deleted. This cannot be undone.
curl -X DELETE https://api.steward.fi/agents/my-agent \
  -H "X-Steward-Key: your-key"

​
Generate Agent Token

Creates a scoped JWT for agent-level operations. 
POST /agents/:agentId/token
Auth: Tenant API key (agents cannot generate their own tokens) Request Body: 
{
  expiresIn?: string; // JWT expiry (e.g., "24h", "7d"). Default: "24h"
}
Response: 
{
  "ok": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "agentId": "my-agent",
    "tenantId": "your-tenant",
    "scope": "agent",
    "expiresIn": "24h"
  }
}

curl -X POST https://api.steward.fi/agents/my-agent/token \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"expiresIn": "24h"}'

​
Get Balance

Returns the native token balance for an agent’s wallet. 
GET /agents/:agentId/balance?chainId=8453
Auth: Agent JWT or tenant key Response: 
{
  "ok": true,
  "data": {
    "agentId": "my-agent",
    "walletAddress": "0x742d35Cc...",
    "balances": {
      "native": "1000000000000000000",
      "nativeFormatted": "1.0",
      "chainId": 8453,
      "symbol": "ETH"
    }
  }
}

const balance = await steward.getBalance("my-agent", 8453);

​
Get Token Balances

Returns ERC-20 token balances for an agent’s wallet. 
GET /agents/:agentId/tokens?chainId=8453&tokens=0xUSDC,0xDAI
Auth: Agent JWT or tenant key Response: 
{
  "ok": true,
  "data": {
    "agentId": "my-agent",
    "walletAddress": "0x742d35Cc...",
    "chainId": 8453,
    "native": {
      "symbol": "ETH",
      "balance": "1000000000000000000",
      "formatted": "1.0"
    },
    "tokens": [
      { "address": "0xUSDC...", "symbol": "USDC", "balance": "1000000", "formatted": "1.0" }
    ]
  }
}

​
Batch Create

Create multiple agents in one request with optional shared policies. 
POST /agents/batch
Auth: Tenant API key Request Body: 
{
  agents: Array<{ id: string; name: string; platformId?: string }>;
  applyPolicies?: PolicyRule[];  // Applied to all created agents
}
Response: 
{
  "ok": true,
  "data": {
    "created": [/* AgentIdentity[] */],
    "errors": [/* { id: string, error: string }[] */]
  }
}

const result = await steward.createWalletBatch(
  [
    { id: "agent-1", name: "Agent One" },
    { id: "agent-2", name: "Agent Two" },
  ],
  [{ id: "limit", type: "spending-limit", enabled: true, config: { maxPerDay: "1000000000000000000" } }]
);