Agent skill

The hodle-api skill is a single SKILL.md file that teaches an agent how to implement against the Hodle API: base URLs, authentication, the endpoint map, the two end-to-end flows, KYC gating, webhook verification, and idempotency/polling guidance. It is public-facing — it never names an upstream provider, and every claim in it traces back to the OpenAPI reference or a page on this site.

Install

npx skills add HodleHub/skills

This adds hodle-api to your agent's local skill set. The skills CLI currently supports Claude Code, Cursor, Codex, and Hermes — the same agents the MCP server targets — so however you already work, the skill loads the same way your other skills do.

What it teaches

Once installed, the skill triggers automatically when you ask an agent to do things like:

• "Integrate the Hodle API"
• "Set up a Pix payout from a stablecoin balance"
• "Wire up Lightning to Pix"
• "Verify Hodle webhooks"
• "Run KYC for a Hodle subaccount"

The skill body covers:

• Base URLs for production and sandbox, and the Authorization: Bearer header every request needs.
• The endpoint map — every path, method, and request/response shape, kept in sync with openapi.json.
• The two end-to-end flows, Stable → Pix and Lightning → Pix, with real request/response bodies.
• KYC gating: which endpoints require APPROVED KYC and what a 403 looks like.
• Webhook HMAC verification, with a worked example.
• Idempotency and polling guidance for payouts and deposits.
• A cross-link to @hodle/mcp for agents that would rather call tools than read curl examples.

Pairing it with the MCP server

The skill and the MCP server solve different problems and are meant to be installed together: the skill is what the agent reads to understand the API's shape and rules, the MCP server is what it calls to actually exercise it. An agent with only the skill still has to construct its own HTTP requests; an agent with only the MCP server has the tools but not the flow guidance or the gating rules around KYC and webhooks. Install both — see MCP server setup — for the full agent-native experience.