Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Obolus Fetch the premium dataset from https://data.example.com/premium"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The name is the coin paid to the ferryman for passage: small denomination, one purpose, spent and gone.
agent → x402_fetch(url) → 402 → sign → pay → bodyx402 has over a thousand listed resources and almost no buyers — a handful of wallets account for nearly all volume, and they are scripted loops rather than agents. The rail exists; nothing can reach it. Obolus is the buyer-side piece: account setup, opt-in, signing and sweeping handled invisibly, so an agent just spends.
/plugin marketplace add inviti8/Obolus
/plugin install obolus@heavymetaWires up the MCP server and adds /obolus:fund-wallet, which knows the bootstrap
order and why it cannot be rearranged. Nothing to install first beyond
uv — the server is launched with uvx obolus mcp.
uv tool install obolusuv tool install rather than uvx for the CLI: uvx re-resolves on every
invocation, measured at 200–400 ms over an installed console script. That is
nothing once per session, which is all the MCP server costs — it is why the
plugin above uses uvx — but it is the wrong trade for a command called in a
loop. pipx install obolus works too.
claude mcp add obolus -e OBOLUS_NETWORK=testnet -- obolus-mcp{
"mcpServers": {
"obolus": {
"command": "obolus-mcp",
"env": { "OBOLUS_NETWORK": "testnet" }
}
}
}It starts on testnet. Mainnet is never disabled — Obolus is meant to make real payments — but it is never what you get by forgetting to choose.
Related MCP server: Slug Wallet
A new vault holds nothing, and the order is forced by the chain:
obolus vault # says which of the three steps you are on
obolus vault qr # scannable codes for the two things you can send# | Step | Who |
1 | Send ≥ 0.21 ALGO to the vault | you |
2 | Opt the vault into USDC ( | Obolus |
3 | Send USDC | you |
Step 3 before step 2 fails. An Algorand account cannot receive an asset it
has not opted into — the transfer is rejected outright, it does not sit pending.
That is why the QR codes encode the asset id and not just the address, and why
wallet_funding_info tells you which step you are on every time rather than only
on error.
The QR codes carry no amount. You type that into your own wallet, where you see it before confirming.
Three tools, deliberately:
Tool | What it does |
| Fetch a URL, paying if it answers |
| Balances, the active session, spending today, the caps. |
| How to put money in. For the human, not the agent. |
There is no tool for any particular merchant. Everything is reached through
x402_fetch, because the moment a wallet grows first-class verbs for one seller
it stops being a wallet.
The session balance, enforced by the chain. Payments come from a short-lived session account funded from your vault, never from the vault itself. A session cannot spend what it does not hold, and that is true regardless of what any code here does.
Everything else is in-process and configurable in config.toml inside your data
directory:
[caps]
session_balance_micro = 5000000 # $5 per session
per_call_micro = 500000 # $0.50 per call
daily_micro = 2000000 # $2 a day, resets 00:00 UTC
allowlist = [] # payTo addresses or hostnames; empty = any
[session]
idle_timeout_seconds = 600 # close and sweep back after this
[files]
# root = "/path/you/choose" # off unless set - see SafetySome refusals are not caps and have no config key: paying an address we control,
a non-https resource on mainnet, an asset the wallet does not hold, and any
challenge that is not a well-formed x402 v2 402.
Your seed is the only way back to your money. It lives in your data
directory. Pointing OBOLUS_DATA_DIR at a new location creates a new wallet; it
does not move the old one. Back the directory up.
File access is off by default. x402_fetch can send a file to a paid
endpoint and write the response back, which is how you get an image signed or a
document processed. Both are disabled unless you set [files] root, and confined
to that directory when you do. This is deliberate: moving bytes off your machine
is not something a spend cap can bound.
Approval is per tool, not per payment. Most MCP clients ask once and remember.
That means the caps above are your real spending boundary, not the prompt — see
DESIGN.md §7.1, which documents what was measured rather than
what was assumed.
A settled payment proves settlement and nothing else — not that the resource was correct, honest, or worth its price.
CLAUDE.md — orientation, and the x402 facts that cost real debugging time to learn.
DESIGN.md — architecture, the security model, and the limitations stated plainly.
IMPLEMENTATION_PLAN.md — build order and what each phase actually proved.
Working on mainnet. On 2026-08-13 and 08-14 an agent used Obolus over MCP to
buy three resources from a live merchant with real USDC — a notarisation at
$0.05, a second at $0.05, and a C2PA signature over a 13 MB TIFF at $0.15. Each
payment came from a disposable session account that was derived, funded, spent
and swept closed; two sessions, both reconciled, nothing stranded. All three
settlements landed with fee: 0, sponsored by the facilitator, as designed.
What that demonstrates is the rail, end to end: an agent with no human in the
loop held a key, answered a 402, and got the bytes. It does not say the
resources were worth their price — settlement proves settlement and nothing more.
Testnet remains the default and the place to develop. Mainnet is guarded, never disabled.
Explain how to put money in this wallet, and report which of the three setup steps the vault is on.
For the human, not the agent - it returns an address and instructions, and no part of it can be automated by the agent.
The three steps are in a forced order: ALGO must arrive before the vault can opt into the payment asset, and the opt-in must happen before USDC can be received at all. USDC sent to a vault that has not opted in is rejected outright - it does not sit pending, it fails.
Each step a human performs carries a scan value: an ARC-26 URI an Algorand
wallet can scan. It encodes the address AND the asset id, so the sender cannot
aim at the wrong asset by hand - which matters because sending the wrong one is
rejected rather than held. No amount is encoded; the human types that into their
own wallet where they see it before confirming.
TOPPING UP ONE ASSET. Pass asset - "ALGO", "USDC", or the asset id - and the
reply narrows to that asset's steps AND includes the QR code as an image, so the
human can scan it directly. ALGO codes are black; the payment asset's are blue
and captioned, so the two are not confused at a glance. Omit asset for the
whole picture as text.
The usual flow: wallet_status answers "how much do I have", then
wallet_funding_info(asset="USDC") answers "I want to top up USDC".
SET open_in_browser WHENEVER A HUMAN WANTS TO SCAN THE CODE. The image block
this returns renders in some MCP clients and not in a terminal, so on its own it
can reach the model and never reach the person holding the phone. With the flag,
Obolus writes a self-contained page and opens it in the default browser - no server
and no network needed.
qr_dir optionally writes the codes as PNG files into that directory, under the
same configured file root as body_file/output_file. obolus vault qr prints them
straight into a terminal.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | No | ||
| qr_dir | No | ||
| open_in_browser | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses that the tool is for a human and cannot be automated, that USDC sent before opt-in is rejected rather than held, that the QR encodes address and asset id but not amount, that image blocks may not render in terminals, and that qr_dir writes files to disk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries substantive guidance: setup order, failure semantics, QR contents, parameter effects, browser behavior, and file output. It is front-loaded with the core purpose and then organized by parameter and usage scenario, so an agent can quickly extract the decision-relevant parts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three optional parameters, no annotations, and no output schema, the description is complete enough for an agent to select the tool and invoke it correctly. It explains what the tool returns, how to choose parameters, the human-only nature, and how it fits alongside wallet_status.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters itself. It covers `asset` values ('ALGO', 'USDC', asset id, or omitted), `open_in_browser` behavior including rendering limitations and the self-contained page, and `qr_dir` including PNG output and the same file root as body_file/output_file.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: it explains how to fund the wallet and reports which of the three setup steps the vault is on. It also clarifies that it returns human-facing address and instructions, and it distinguishes itself from wallet_status by naming the usual flow where wallet_status answers balances and wallet_funding_info answers top-up questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: pass `asset` to narrow to one asset and omit it for the full picture, set `open_in_browser` when a human wants to scan the code, and provides the sibling relationship by saying wallet_status is for 'how much do I have' while wallet_funding_info is for 'I want to top up USDC'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the wallet's state: network, vault address and balances, the active session and what remains in it, spending so far today, and the configured caps.
Read this before assuming a payment can be made. A vault that is not yet funded or not yet opted into the payment asset cannot pay for anything, and this is where that shows up. Costs nothing and spends nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it succeeds: 'Costs nothing and spends nothing' explicitly discloses that invocation has no monetary or spend effect. The word 'Report' also signals a read-only operation, and the note about where funding problems show up adds useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with no filler. The first sentence front-loads the tool's output contents, and the second adds essential usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only status tool with an output schema available, the description is complete: it states what is returned, when to read it first, and that it has no cost or side effects. Nothing essential is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add beyond the schema. This matches the baseline of 4 for a parameterless tool; no parameter explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and clearly identifies the resource as the wallet's state, enumerating the exact contents: network, vault address, balances, active session, spending, and caps. It is clear and informative, though it does not explicitly distinguish itself from the sibling wallet_funding_info, which may overlap on balances and vault details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context for when to use the tool: 'Read this before assuming a payment can be made.' It explains why that matters by noting unfunded or non-opted-in vaults cannot pay. It does not explicitly mention alternatives or exclusion conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a URL, paying automatically if it answers with an x402 payment challenge.
SPENDS REAL MONEY when the network is mainnet. Payment comes from a short-lived session account funded from the user's vault, never from the vault itself, so the most any single call can lose is the session balance.
Returns the response body plus, when a payment happened, the price, the merchant address, the transaction id and the settlement receipt.
What the receipt proves: that this payment settled on chain. It does NOT prove the resource was correct, honest, or worth the price - a settled payment and a useful answer are different claims.
Refuses, without spending, when: the price exceeds max_price_usdc or the configured per-call cap; the day's spending cap would be exceeded; the merchant is outside an allowlist the user enabled; the resource asks for an asset this wallet does not hold; the payTo address is one of ours (paying yourself is not a payment); or a mainnet resource is not https. Each refusal says which rule it hit.
Unpaid URLs are fine - if the server answers normally, the body is returned and nothing is spent.
FILES. body_file sends the bytes at a path instead of body, and
output_file writes the response to a path instead of returning it inline. Use
them for anything binary or large - an image to be signed, a document to be
processed - because binary cannot survive being passed as text and a large body
would swamp the conversation. Both are confined to a directory the user
configured, and both are DISABLED unless they configured one; a path outside it
is refused. Pass body or body_file, never both.
JSON. Pass body as an object or array, not as a string of JSON - it is sent as
application/json and you do not need to set content_type. A string body is
sent verbatim, which is what you want for text, XML or form encoding. If the exact
bytes matter - anything the endpoint hashes or signs over - use body_file, which
is never re-encoded.
content_type sets the request's Content-Type. Some paid endpoints require it
and reject the request without it - AFTER taking payment, because the payment is
verified before the handler runs. Set it whenever the body is not plain text.
Response headers the merchant set are returned under response_headers; some
endpoints put results there that appear nowhere in the body.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| body | No | ||
| method | No | GET | |
| body_file | No | ||
| output_file | No | ||
| content_type | No | ||
| max_price_usdc | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It candidly states that real money can be spent on mainnet, that losses are capped at the session balance, that the receipt does not prove resource quality, and that refusals occur without spending. It also discloses file path confinement and the payment-before-verification risk with content_type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly structured with bolded section headers and front-loaded risk warnings. Every section addresses a practical operational concern, and the length is justified by the payment risk and param complexity. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-stakes tool with no annotations, the description is nearly complete: it covers spending limits, refusal conditions, return fields, file handling, JSON serialization, and content_type pitfalls. The only notable omission is guidance for the `method` parameter, which prevents a perfect completeness score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does an excellent job explaining body, body_file, output_file, content_type, max_price_usdc, and url behavior. However, the `method` parameter is never mentioned, leaving a gap for agents unsure whether to send GET, POST, or other methods.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch a URL, paying automatically if it answers with an x402 payment challenge.' It clearly distinguishes this from the sibling wallet_status and wallet_funding_info tools by making it a network-fetch/payment tool rather than a wallet inspection tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: when payment happens, when it refuses without spending, that unpaid URLs are safe, and when to choose body_file vs body vs output_file. It also warns about content_type and binary payloads. These are concrete, decision-relevant conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool covers a distinct part of the workflow: fetching a paid URL, inspecting wallet state, and getting funding instructions. There is no meaningful overlap or likely misselection between them.
All names are lowercase snake_case and clearly grouped by domain: x402_fetch for the payment fetch action, wallet_status and wallet_funding_info for wallet concerns. The one minor inconsistency is that x402_fetch is verb-led while the other two are noun-led, but the pattern is still predictable and readable.
Three tools is small but ideal for this narrow purpose: one action tool, one status tool, and one funding-info tool. Each earns its place and none feel redundant.
The set covers the full user journey: check if the wallet can pay, perform the paid fetch, and get funding instructions if the wallet cannot pay. Minor gaps exist, such as no tool for adjusting caps or spending limits, but those appear to be intentionally configuration-level concerns rather than agent actions.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
15 paid AI agent primitives via x402 (USDC on Base). Pay-per-call MCP server.
Policy-gated MCP treasury for AI agents — x402 subscribe, 50+ tools, multi-chain.
Agent-commerce MCP server for x402/USDC payments and affiliate splits on Base.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/inviti8/Obolus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
