hogswap-mcp
# hogswap-mcp
MCP server exposing [HOGSWAP](https://hogswap-v1.liquihog.dev) to AI
agents: DEX-aggregated quotes, unsigned swap builds, zero-human API-key
self-registration, and the star — **`pay_x402_invoice`**: pay any
Algorand-settled x402 invoice with any 1–4 assets you hold, via an
exact-out router swap. API reference:
[hogswap-v1.liquihog.dev/reference](https://hogswap-v1.liquihog.dev/reference).
Building an app rather than an agent? Official SDKs:
[`hogswap-js-sdk`](https://github.com/LiquiHog/hogswap-js-sdk) (npm)
and [`hogswap-py-sdk`](https://github.com/LiquiHog/hogswap-py-sdk) (PyPI).
Strictly non-custodial: every transaction-producing tool returns
**unsigned** groups; you sign with your own wallet tooling and submit
yourself. Never give any tool a mnemonic or private key.
## Run (stdio)
```sh
npm install
HOGSWAP_API_KEY=hsk_... node src/index.mjs # key optional
```
Claude Code: `claude mcp add hogswap -e HOGSWAP_API_KEY=hsk_... -- node <abs-path>/src/index.mjs`
| Env | Meaning |
|---|---|
| `HOGSWAP_API_URL` | API base (default `https://hogswap-v1.liquihog.dev`) |
| `HOGSWAP_API_KEY` | `hsk_` bearer key; self-issue via the `register_agent` / `verify_registration` tools |
## Tools
Free (no key): `list_payable_assets`, `get_quote`, `register_agent`,
`verify_registration`. `get_quote` takes optional `max_legs` (1–16)
to cap total route legs, splits included — for replaying the route
under your own resource budget.
🔑 Require a HOGSWAP API key (set `HOGSWAP_API_KEY`, or self-issue one
with `register_agent` → sign → `verify_registration`): `build_swap`,
`pay_x402_invoice`, `get_credit_offer`, `get_balance`, plus the watch
tools `set_watch` / `list_watches` / `delete_watch` (standing
server-side price/target alerts — free of charge, but namespaced by
key). Without a key these return an auth error, not a build.
Watch fires are numbers-only hints — re-quote with `get_quote` when
one fires. From MCP, poll `list_watches`; outside MCP the server
pushes events over SSE at `GET /watches/stream`.
`pay_x402_invoice` returns two groups (swap, then payment) — sign all
txns in one pass, submit the groups in order; the swap's on-chain
floor guarantees the payment is funded. A HOGSWAP credit top-up's 402
offer is itself an x402 invoice: feed its `accepts[0]` (with the
`note` nonce) straight into `pay_x402_invoice` to buy credits with
any asset.
## Remote (no local process)
The same 12 tools are served over MCP Streamable HTTP at
`https://hogswap-v1.liquihog.dev/mcp/` — hosted by the HOGSWAP API
itself, no local process needed. **Use the trailing slash** — the
bare `/mcp` 307-redirects to `/mcp/`, costing an extra round trip per
call. Point any remote-capable MCP client at it; pass your key as
`Authorization: Bearer hsk_...` (the Claude API connector's
`authorization_token` does exactly this).
## Smoke tests
```sh
HOGSWAP_API_KEY=hsk_... \
SMOKE_PAY_TO=<any USDC-opted addr> node test/smoke.mjs # stdio
HOGSWAP_API_KEY=hsk_... \
SMOKE_PAY_TO=<any USDC-opted addr> node test/smoke-remote.mjs # remote
```
Both default to the live API; set `HOGSWAP_API_URL` (stdio) or
`MCP_URL` (remote) to point them at another instance. Read-only +
build-only; nothing is signed or broadcast.
TDQS
Scored across 8 tools
Each tool targets a distinct action in the HOGSWAP workflow: listing assets, checking balance, getting quotes, building swaps, paying invoices, registering, verifying, and creating credit offers. The sequential dependencies (quote -> build -> pay; register -> verify) are clear, and no two tools appear to duplicate functionality.
All tool names follow a consistent verb_noun snake_case pattern: list_, get_, build_, pay_, register_, verify_. There is a minor mix of 'list' vs 'get' for retrieval operations, but it is semantically appropriate (listing a collection vs fetching a specific balance/quote), and the overall convention is uniform.
With 8 tools, the server is well-scoped for its purpose—covering authentication, asset discovery, quoting, swap construction, invoice payment, balance checking, and credit top-ups. Each tool earns its place, and the count sits comfortably within the ideal 3-15 range.
The tool surface fully covers the core lifecycle: registration (register_agent + verify_registration), credit management (get_balance, get_credit_offer, pay_x402_invoice), and swap execution (list_payable_assets, get_quote, build_swap). Transaction submission is intentionally external for security, so there are no dead ends in the workflow.