Hodle for AI agents
How an AI agent builds on the Hodle Platform API — read/write split, sandbox-first posture, and where to start.
The Hodle API is built to be called by a person's code, and just as easily by an AI agent acting on that person's behalf. Every endpoint documented in this site — quotes, KYC, wallets, deposits, payouts, Lightning invoices, webhooks — is reachable the same way whether the caller is a human-written script or an agent loop.
This section is the entry point for agent-side integration. It covers:
- The MCP server — a stdio Model Context Protocol
server,
@hodle/mcp, that wraps the public REST API as typed tools an agent can call directly from Claude Code, Cursor, Codex, or Hermes. - The agent skill — a
SKILL.mdfile, installable withnpx skills add, that teaches an agent how to implement against the Hodle API without reading this whole site first.
What an agent can do here
Everything in the full API reference is available to an agent, split into two shapes:
- Read tools — pricing quotes, KYC status, wallet balances, account statements, payout status, subaccount lookups. These never move funds and are always available.
- Write tools — Pix payouts, stablecoin transfers, deposit charges, Lightning invoices, subaccount creation, KYC attempts. These move real value or create durable state, so they are opt-in and require an explicit confirmation on every call.
The read/write split is enforced at the transport level, not just by convention: a
deployment that never sets HODLE_MCP_ALLOW_WRITES=true cannot see the write tools at
all, and a write tool call without confirm: true is refused before any request reaches
the Hodle API. See the MCP page for the exact tool list and gating.
Sandbox first
Point an agent at https://sandbox-api.hodle.com.br with a hodle_test_ key and it can
run the full integration — subaccounts, KYC, quotes, wallets, deposits, payouts,
Lightning invoices — against real handlers with no real money moving. See
Sandbox for how the simulated settlement works. Both @hodle/mcp and
the agent skill default to the sandbox host: pointing at production is a deliberate,
explicit choice, never the default.
Where to next
- MCP server setup — install
@hodle/mcpin your agent of choice and see the full tool table. - Agent skill — install the
hodle-apiskill for implementation guidance an agent can read on demand. - Authentication, Sandbox, Webhooks — the same reference pages a human integrator uses.