Agents

What is an Agent?

An agent in Wallgent is the combination of three things provisioned as a single unit:

• A wallet — holds the agent's funds, isolated from your organization wallet
• A wallet-scoped API key — the agent authenticates with this key and can only touch its own wallet
• Spend policies — rules that govern what the agent can and cannot spend (optional, configured separately or via templates)

Agents use walletType: AGENT, which distinguishes them from your main organization wallet (walletType: ORG). This distinction is enforced throughout the API: agent endpoints only operate on AGENT wallets, and scoped keys cannot access wallets they are not bound to.

Wallgent's agent primitive is the cornerstone feature of the platform — it is how you give an AI model its own treasury with guardrails, rather than having all your automations share a single wallet.

Create an Agent

import Wallgent from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

const agent = await wg.agents.create({
  name: 'Marketing Agent',
})

console.log(agent.id)        // wal_01J... — wallet ID, also the agent ID
console.log(agent.apiKey)    // wg_test_... — save this immediately, it is shown once
console.log(agent.apiKeyId)  // key_... — use this to manage or rotate the key
console.log(agent.balance)   // '0.00000000'

The response includes the raw API key exactly once. Store it securely (e.g., in your secrets manager) — the Wallgent API only stores a SHA-256 hash and cannot return the key again. To get a new key, use rotateKey.

Default permissions granted to the agent key: wallets:read, wallets:write, payments:read, payments:write. You can override these:

const agent = await wg.agents.create({
  name: 'Read-only Analyst',
  permissions: ['wallets:read', 'payments:read'],
})

Create from a Template

Templates provision an agent with pre-configured spend policies tuned for a specific use case. Pass templateId to POST /v1/agents/from-template:

const agent = await wg.agents.create({
  name: 'My Procurement Bot',
  templateId: 'procurement',
})

// Response also includes policyId — the policy created from the template
console.log(agent.policyId)

Note: the SDK's create method maps to POST /v1/agents for plain creation. For template creation, call the REST endpoint directly or use the MCP tool wallgent_create_agent with a templateId if your integration supports it. The REST endpoint is POST /v1/agents/from-template.

Available Templates

Templates with $0 limits are monitoring or reporting agents — they have read-only permissions and do not send payments.

Retrieve the full template list at any time:

GET /v1/agents/templates

List and Retrieve Agents

// List all agents
const { data } = await wg.agents.list()

// Paginate
const { data, cursor, hasMore } = await wg.agents.list({ limit: 20, cursor: '...' })

// Get a single agent with its active API key metadata
const agent = await wg.agents.retrieve('wal_01J...')
console.log(agent.apiKey.lastUsedAt)

Budget Management

Agents start with a zero balance. Fund an agent by adjusting its budget — funds are transferred from your organization wallet to the agent wallet atomically via the Wallgent ledger.

Add funds

Pass a positive number to credit the agent:

const result = await wg.agents.adjustBudget('wal_01J...', { amount: 100 })
console.log(result.newBalance) // '100.00000000'

Remove funds

Pass a negative number to debit the agent and return funds to the org wallet:

const result = await wg.agents.adjustBudget('wal_01J...', { amount: -50 })
console.log(result.newBalance) // '50.00000000'

The API responds with:

{
  "id": "wal_01J...",
  "adjustment": 100,
  "newBalance": "100.00000000",
  "currency": "USD"
}

The underlying transfer is a double-entry ledger transaction: your org wallet is debited and the agent wallet is credited (or vice versa). Both wallets must be ACTIVE and in the same environment.

Pause and Resume

Pausing an agent freezes its wallet — all payment attempts will be rejected with WALLET_FROZEN while frozen. The agent's API key remains valid but unusable for payments.

// Pause (freeze wallet)
await wg.agents.pause('wal_01J...')
// Response: { id: 'wal_01J...', status: 'FROZEN' }

// Resume (unfreeze wallet)
await wg.agents.resume('wal_01J...')
// Response: { id: 'wal_01J...', status: 'ACTIVE' }

Use pause when you need to halt an agent's activity without deleting it — for example, when an agent behaves unexpectedly or you need to investigate its transaction history before allowing further spending.

Rotate the API Key

Rotating the key immediately revokes the old key and issues a new one with the same permissions and wallet scope. The new key is shown once in the response.

const { apiKey, apiKeyId, revokedKeyId } = await wg.agents.rotateKey('wal_01J...')

console.log(apiKey)      // wg_test_... — new key, shown once
console.log(revokedKeyId) // key_... — the revoked key ID

Rotation is atomic — there is no window where neither key is valid. Update the agent's runtime secret store immediately after rotating.

Delete an Agent

Deleting an agent:

1. Sweeps any remaining balance back to the organization wallet
2. Freezes the agent wallet
3. Revokes all scoped API keys for that agent

const { deleted, sweptAmount } = await wg.agents.delete('wal_01J...')
console.log(sweptAmount) // '47.50000000' — amount returned to org wallet

Deletion is permanent. The wallet record is preserved in the ledger for audit purposes but can no longer be used.

API Endpoints

All endpoints require wallets:read for GET requests and wallets:write for all others.

MCP Tools

Permissions