How AI Agents Use Aleo

AI agents interact with Aleo through the TypeScript SDK, the REST API, and Developer Skills that teach correct Leo patterns. Aleo's privacy model means agents can transact without exposing strategy, balances, or counterparties to external observers.

When an AI agent operates on a public blockchain, every action it takes is permanently visible. Its wallet address, its balance, every transfer and contract interaction, every staking delegation: all indexed and available to anyone with a block explorer.

That creates real problems.

Competitive exposure. If your agent executes a trading strategy, buys compute, or acquires data on your behalf, competitors can monitor the wallet and reverse-engineer the strategy. An agent that pays for API access to a particular data provider reveals which data you value. An agent that stakes with a particular validator reveals your infrastructure preferences.

Front-running and MEV extraction. On public chains with visible mempools, pending transactions can be observed before finalization. Miners, validators, and specialized bots reorder, insert, or sandwich transactions to extract value. Agents transact programmatically and often at high frequency, which makes them especially exposed to this.

Profiling and targeting. A public wallet controlled by an AI agent becomes a target. The wallet's transaction graph reveals relationships: which contracts the agent calls, which addresses it sends to, which tokens it holds. That graph is a dataset for anyone who wants to understand, compete with, or attack your business.

Aleo addresses these problems at the protocol level. Transactions use zero-knowledge proofs to validate state transitions without revealing the underlying data. An agent can hold a balance, make transfers, and interact with programs without exposing any of that activity to external observers. The chain verifies that every transaction is valid - sufficient funds, correct program logic, no rule violations - but the details stay private by default.

Records (Aleo's equivalent of UTXOs) are encrypted to their owner. Program inputs and outputs can be private. The zero-knowledge proof system (Varuna) lets validators confirm correctness without seeing data.

An agent that cannot protect its on-chain activity is an agent whose operator is exposed.

Agents interact with Aleo through two main interfaces: the TypeScript SDK for full transaction capabilities, and the REST API for read operations.

The SDK (@provablehq/sdk)

The Aleo SDK is a TypeScript library that provides complete access to the Aleo network. An agent running in Node.js can:

• Create and sign transactions - transfers, program executions, deployments
• Generate zero-knowledge proofs - client-side proving using the companion WASM package (@provablehq/wasm)
• Decrypt records - read private state owned by the agent's address
• Read public state - query mappings, balances, program source code
• Manage accounts - generate keys, derive addresses, sign messages

Example: reading a public mapping value:

import { AleoNetworkClient } from "@provablehq/sdk";

const client = new AleoNetworkClient("https://api.explorer.provable.com/v1");
const value = await client.getProgramMappingValue(
  "credits.aleo",
  "account",
  "aleo1abc..."
);

Example: creating a transfer:

import { ProgramManager } from "@provablehq/sdk";

const pm = new ProgramManager("https://api.explorer.provable.com/v1");
pm.setAccount(account);
const tx = await pm.transfer(amount, recipient, "private", fee);

The SDK handles proof generation, record selection, and transaction construction. The agent calls high-level methods and gets back transaction IDs.

The REST API

Every Aleo node exposes a REST API for reading chain state. Agents that only need read access can use HTTP requests without the SDK:

• GET /testnet/latest/height - current block height
• GET /testnet/program/{program_id} - program source code
• GET /testnet/program/{program_id}/mapping/{mapping_name}/{key} - mapping value
• GET /testnet/transaction/{tx_id} - transaction details
• GET /testnet/block/{height} - block data

The public API at api.explorer.provable.com is available without authentication. Both /v1 and /v2 endpoint paths are supported; v2 is the current documented version. The SDK currently defaults to v1 paths internally. For production agents that need higher throughput or privacy, run your own node.

Wallet adapters

For agents that interact with users or need human-in-the-loop signing, the wallet adapter library (@demox-labs/aleo-wallet-adapter) provides a framework-agnostic interface. This lets agents propose transactions that a human approves through their wallet (Leo Wallet, Puzzle Wallet, or others).

This pattern is useful when you want agent autonomy for read operations and analysis, but require human approval for any transaction that moves value.

AI coding agents are only as good as their context. Leo is a specialized language for zero-knowledge circuits, and most LLMs have limited or outdated knowledge of its syntax. Developer Skills solve this by injecting version-specific Leo knowledge directly into the agent's context window.

What skills provide

Each skill is a markdown file containing curated documentation, canonical code patterns, compiler rules, and common error resolutions for a specific domain:

• Smart Contracts - Leo syntax, types, records, mappings, constructors, final { } blocks
• Deployment - build, deploy, execute, upgrade workflow with Leo CLI and snarkOS
• Frontend Integration - SDK setup, wallet adapters, browser proof generation
• Privacy Patterns - record-based privacy, shielding/unshielding, commit-reveal
• Testing - @test and @should_fail annotations, devnet setup, debugging
• Staking & Delegation - validator operations, staking mechanics, credit management
• Backend Integration - server-side SDK usage, node API patterns

Installing skills

One command installs skills for your detected agent harness:

curl -fsSL https://aleoforagents.com/skills.sh | bash

The installer auto-detects Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, Amp, Aider, Cline, Roo Code, Continue, OpenCode, OpenClaw, Nanobot, MiniClaw, IronClaw, ZeroClaw, NanoClaw, PicoClaw, and other AgentSkills-compatible frameworks. It installs to the correct location for each tool (e.g., .cursor/rules/ for Cursor, CLAUDE.md pointers for Claude Code, AGENTS.md for Codex and Amp, SKILL.md directories for OpenClaw ecosystem).

See the Skills documentation for full details.

Here are concrete workflows agents can execute on Aleo today.

Write and deploy a Leo program

An agent with skills loaded can generate Leo code, compile it, fix errors, and deploy:

1. Agent writes Leo program based on your specification
2. Agent runs leo build to compile - reads error output if compilation fails
3. Agent fixes issues using skill knowledge and compiler diagnostics
4. Agent runs leo run with test inputs to verify behavior
5. Agent deploys to testnet via snarkos developer deploy

This loop works with any agent that can execute shell commands. Skills provide the Leo knowledge; the compiler provides the feedback.

Monitor balances and state

An agent can poll the REST API or SDK to watch for changes:

• Track private record balances for threshold alerts
• Monitor public mapping state for protocol changes
• Watch staking positions and reward accruals
• Verify counterparty program logic before interacting

All read operations are safe - they require no signing and cannot modify state.

Execute program functions

An agent with SDK access and a private key can call any deployed program's functions:

1. Agent reads the target program's source to understand its interface
2. Agent constructs the function call with correct inputs
3. SDK generates the zero-knowledge proof locally
4. Transaction is broadcast to the network
5. Agent confirms execution by checking transaction status

Because proof generation happens locally, the network never sees the agent's inputs. The transaction is private by default.

Agents operating on any blockchain need careful security design. Aleo's privacy reduces the attack surface - competitors cannot observe transactions - but key management and access control are still your responsibility.

Key storage. Never embed private keys in prompts, logs, or source code. Use environment variables with restricted access, a secrets manager (AWS Secrets Manager, HashiCorp Vault), or a hardware security module for production deployments. Use a clearly fake placeholder like ALEO_PRIVATE_KEY=<your-key-here> in documentation and examples.

Principle of least privilege. Give agents only the access they need. A monitoring agent needs read-only API access. A deployment agent needs the Leo CLI. Only agents that must move value need a private key.

Human-in-the-loop for high-value operations. Use wallet adapters or a separate approval service for transactions above your risk threshold. The agent proposes; a human approves.

Testnet first. Always develop and test agent workflows on testnet before mainnet. Testnet credits are free and have no monetary value.

1. Install Developer Skills for your AI coding agent:

curl -fsSL https://aleoforagents.com/skills.sh | bash

2. Install the SDK for programmatic access:

npm install @provablehq/sdk @provablehq/wasm

3. Try a read operation to confirm connectivity:

import { AleoNetworkClient } from "@provablehq/sdk";
const client = new AleoNetworkClient("https://api.explorer.provable.com/v1");
const height = await client.getLatestHeight();
console.log("Current block height:", height);

4. Ask your agent to write a Leo program. With skills loaded, the agent has current Leo syntax knowledge. Start with a simple program (private token, counter) and deploy to testnet.

5. Read the developer guide for full details on Leo, deployment, and the Aleo ecosystem.