diff --git a/SUMMARY.md b/SUMMARY.md index d234aa0..4ef4d8b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -115,7 +115,9 @@ * [Introduction](obol-stack/README.md) * [Quickstart](obol-stack/quickstart.md) * [Build a Profitable Obol Stack](obol-stack/build-a-profitable-stack.md) +* [Agents & Skills](obol-stack/agents-and-skills.md) * [Selling Agent Services](obol-stack/selling-services.md) +* [Buying Services](obol-stack/buying-services.md) * [Set up a Permanent URL](obol-stack/permanent-url.md) * [Installing Networks](obol-stack/installing-networks.md) * [Installing Apps](obol-stack/installing-apps.md) diff --git a/obol-stack/README.md b/obol-stack/README.md index 8f7db1b..6f81208 100644 --- a/obol-stack/README.md +++ b/obol-stack/README.md @@ -128,7 +128,9 @@ Running full Ethereum nodes requires significant disk space. Mainnet execution c - [Quickstart](quickstart.md) — install the stack, talk to your agent, and run `obol sell demo`. - [Build a profitable Obol Stack](build-a-profitable-stack.md) — end-to-end: bounded archive node → index → paid service → specialized agent → listed on marketplaces. +- [Agents & Skills](agents-and-skills.md) — create specialised sub-agents and see the embedded skill set they ship with. - [Selling agent services](selling-services.md) — full orientation on the three `sell` shapes, x402 economics, ERC-8004 registration, and Telegram notifications. +- [Buying services](buying-services.md) — rent remote models with `obol buy inference`, or pay any x402 endpoint from your agent. - [Installing Networks](installing-networks.md) — sync Ethereum / Aztec, including bounded archives via `--since`. ## Need assistance? diff --git a/obol-stack/agents-and-skills.md b/obol-stack/agents-and-skills.md new file mode 100644 index 0000000..926f870 --- /dev/null +++ b/obol-stack/agents-and-skills.md @@ -0,0 +1,100 @@ +--- +description: Create specialised sub-agents, manage their wallets, and understand the skills your agents ship with +--- + +# Agents & Skills + +## The default agent + +`obol stack up` creates a default **Hermes** agent in the `hermes-obol-agent` namespace, with its own Ethereum signing wallet (backed by an in-cluster remote signer — the agent never touches raw private keys) and a full embedded skill set. Talk to it with `obol hermes chat`, get its API bearer token with `obol agent auth`. + +{% hint style="warning" %} +Back up the agent's wallet before you put anything on it. Losing the keystore loses the agent's on-chain identity and funds. + +```shell +obol agent wallet backup -o ~/obol-wallet-backup.json --passphrase "..." +``` + +Store the backup **outside** `~/.config/obol/` — `obol stack purge -f` deletes that directory. +{% endhint %} + +## Creating sub-agents + +Additional agents are where the Stack gets interesting: each one is a separate, long-lived specialist with its own namespace, state, skills, and (optionally) its own wallet. + +```shell +obol agent new research \ + --model qwen3.5:9b \ + --skills ethereum-networks,buy-x402,indexing \ + --objective "Research onchain data and sell reports. Cite the block number your data came from." \ + --create-wallet +``` + +* `--objective` becomes the agent's identity — spend real effort on it: scope, output format, refusal policy, tone. One sharp paragraph beats a page of vibes. +* `--skills` should be **narrow**. A specialist selling on-chain analysis doesn't need generalist skills; a tight list keeps a smaller model focused and makes the agent's edge legible to buyers. +* `--create-wallet` gives the sub-agent its own wallet. Skip it if the agent doesn't need to hold or sign funds — payments for its services can go to your main agent's wallet instead. + +Manage the fleet: + +```shell +obol agent list # all agents +obol agent auth research # bearer token for a specific agent +obol agent sync # re-render agent deployments after config changes +obol agent delete research # remove one +``` + +An agent created this way can be put on sale in one command — `obol sell agent research --price 0.05 --token USDC --chain base` — turning it into an OpenAI-compatible paid endpoint. See [Selling Agent Services](selling-services.md). + +{% hint style="info" %} +OpenClaw remains supported as an alternate runtime: `obol agent new --runtime openclaw`, then `obol openclaw dashboard`. +{% endhint %} + +## Embedded skills + +Every agent ships with Obol's embedded skills — self-contained playbooks (instructions + scripts) the agent loads on demand. The default set gives your agent working knowledge of the commerce loop, Ethereum, and its own cluster: + +### Commerce & agents + +| Skill | What the agent can do with it | +| ----- | ----------------------------- | +| `sub-agent-business` | Design, evaluate, price, and sell specialised sub-agents people pay per turn — the business playbook | +| `agent-factory` | Spawn durable child agents with their own namespace, wallet, skills, and paid endpoint | +| `sell` | Create and manage payment-gated ServiceOffers, track reconciliation, register on ERC-8004 | +| `monetize-guide` | Guided end-to-end walkthrough for selling inference or an HTTP API | +| `buy-x402` | Buy from any x402 endpoint — probe pricing, pre-sign payments, auto-refill, check balances | +| `discovery` | Find agents registered on the ERC-8004 Identity Registry across chains | +| `swap` | Treasury moves — swap USDC/ETH/OBOL on Base and mainnet via Uniswap V3, with quotes and slippage guards | +| `autoresearch` / `autoresearch-coordinator` / `autoresearch-worker` | Run, coordinate, or sell GPU time for autonomous LLM optimization experiments | + +### Ethereum + +| Skill | What the agent can do with it | +| ----- | ----------------------------- | +| `ethereum-networks` | Read-only chain queries via the local RPC gateway — blocks, balances, contract reads, ERC-20, ENS | +| `ethereum-local-wallet` | Sign and send transactions via the per-agent remote signer | +| `addresses` | Verified contract addresses — payment rails first, then DeFi, tokens, bridges, registries | +| `building-blocks` | DeFi protocol composability — Uniswap, Aave, Aerodrome, Pendle | +| `concepts` | The onchain mental model — state machines, incentives, why nothing is automatic | +| `gas` | Real transaction costs today, mainnet vs L2 | +| `indexing` | Reading historical onchain data at scale — The Graph, Dune, Ponder, event-first design | +| `l2s` | The L2 landscape — which chain for which job | +| `standards` | ERC-8004, x402, EIP-3009, EIP-7702, ERC-4337 | +| `wallets` | Wallet architecture and key safety for AI agents | +| `why` | Why Ethereum for agents — the ERC-8004 + x402 loop | + +### Operations + +| Skill | What the agent can do with it | +| ----- | ----------------------------- | +| `obol-stack` | Kubernetes diagnostics from inside the cluster — pods, logs, events | +| `distributed-validators` | Obol DVT cluster monitoring via the Obol API | + +The list evolves — ask your agent, or run: + +```shell +obol hermes skills list # live catalogue (default agent) +obol hermes skills add # add a skill +obol hermes skills remove # remove one +``` + +Custom skills are just directories with a `SKILL.md` — drop your own curated data and playbooks into an agent's skills directory to give it an edge nobody else has. That curation is exactly what makes a sub-agent worth paying for: see [Build a Profitable Obol Stack](build-a-profitable-stack.md). diff --git a/obol-stack/build-a-profitable-stack.md b/obol-stack/build-a-profitable-stack.md index cc5882d..b22a9b0 100644 --- a/obol-stack/build-a-profitable-stack.md +++ b/obol-stack/build-a-profitable-stack.md @@ -67,7 +67,7 @@ obol sell http my-index \ --per-request 0.001 \ --chain base \ --token USDC \ - --wallet 0x...your-wallet... + --pay-to 0x...your-wallet... ``` Confirm it reconciles to `Ready`: @@ -124,10 +124,7 @@ Confirm it's live with `obol tunnel status`. For the full dashboard walkthrough Register your agent on [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) so buyers can find it: ```shell -obol sell register \ - --chain mainnet \ - --name my-quant \ - --private-key-file ~/.config/obol/agents/my-quant/wallet.json +obol sell register --chain mainnet --name my-quant ``` Registration writes to the on-chain Identity Registry. From there, multiple marketplaces and explorers index your offer: diff --git a/obol-stack/buying-services.md b/obol-stack/buying-services.md new file mode 100644 index 0000000..ac1f345 --- /dev/null +++ b/obol-stack/buying-services.md @@ -0,0 +1,67 @@ +--- +description: Rent a remote model with obol buy inference, or pay any x402 endpoint straight from your agent +--- + +# Buying Services + +The Obol Stack closes the commerce loop from both sides. Selling is covered in [Selling Agent Services](selling-services.md); this page is the buy side — how to spend from your agent's wallet on other people's services. + +There are two distinct buy paths. Don't conflate them: + +* **Buying inference is renting a brain.** You have no local Ollama, no provider API key, or you want a hosted model you don't otherwise have access to. What you get back is tokens. +* **Buying from an agent is renting specialised work.** You pay another agent per turn for a task — analysis, monitoring, drafting — not per token for completions. Drive this from `obol hermes chat`; your agent's embedded `buy-x402` skill handles the probe-pay-consume loop. + +## Rent a model: `obol buy inference` + +```shell +obol buy inference https://seller.example/ +``` + +Point it at any Obol Stack storefront URL (or omit the URL to use the default storefront). The command: + +1. Walks the seller's `/api/services.json` catalog and resolves the model and payment token from the offer. +2. Prompts you through the purchase on a TTY: auto-top-up yes/no → how many requests, with a cost preview → final confirmation. +3. Pre-signs payment authorizations via your agent's remote signer and creates a `PurchaseRequest`. +4. Publishes the model as `paid/` through your cluster's LiteLLM. + +After that, the remote model is just another model in your roster. Your agent (or any OpenAI-compatible client pointed at LiteLLM) can call it, and the in-cluster `x402-buyer` sidecar spends exactly one pre-signed authorization per request — **your maximum loss is bounded by what you pre-authorized**, and your agent never touches raw keys. + +### Useful flags + +```shell +obol buy inference https://seller.example/ --agent research # pay from agent `research`'s wallet + # and switch only that agent to the paid model +obol buy inference https://seller.example/ --set-default # promote the paid model globally, sync every agent +``` + +| Flag | What it does | +| ---- | ------------ | +| `--model ` | Pick a model when the seller offers several on one URL | +| `--count ` / `--budget ` | Size the purchase non-interactively (CI / scripts) | +| `--auto-refill` | Let the agent top up the budget when it runs low (`--refill-threshold`, `--refill-count`) | +| `--cost-cap ` | Refuse refills if the seller raises the per-request price above this ceiling | +| `--expected-agent-id ` | Opt-in ERC-8004 identity check of the seller (skipped by default) | + +{% hint style="info" %} +Call paid models with `"stream": true`. Responses buffered longer than ~100 seconds get dropped by Cloudflare quick tunnels on the seller side — streaming keeps the wire warm. +{% endhint %} + +## Pay any x402 endpoint from your agent + +Your agent ships with the `buy-x402` skill, which can probe and pay arbitrary x402-gated endpoints — one-shot HTTP calls, paid agent turns, or batch pre-authorizations. Just ask it in `obol hermes chat`: + +> "Probe https://seller.example/services/quant and tell me what it costs. If it's under 0.05 USDC per request, pay for one analysis of ETH gas trends." + +The skill checks pricing from the `402 Payment Required` response before spending, supports USDC (EIP-3009) and OBOL (Permit2), and tracks balances — ask your agent for `balance` any time. + +## Prefer a cloud provider instead? + +If you just want a good model and don't need the crypto rails, bring your own key: + +```shell +obol model setup # interactive picker (defaults to OpenRouter + free models) +obol model setup --provider anthropic --api-key sk-ant-... +obol model setup custom --endpoint http://192.168.1.20:8000/v1 --model my-model # any OpenAI-compatible endpoint +``` + +`obol buy inference` and `obol model setup` end in the same place — a model your agents can use — they just differ in who you pay and how. diff --git a/obol-stack/faq.md b/obol-stack/faq.md index e9b325d..f4685c0 100644 --- a/obol-stack/faq.md +++ b/obol-stack/faq.md @@ -161,13 +161,21 @@ USDC and other tokens settle on the rail their issuer supports (EIP-3009 for USD ### How do I list my service on a public agent registry? ```shell -obol sell register --chain mainnet --name my-service --private-key-file +obol sell register --chain mainnet --name my-service ``` This publishes the agent's wallet + service catalog to the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry on the chain you specify. Note that this requires ETH on the registering wallet for gas. `obol sell demo` deliberately skips registration by default — run `obol sell register` later when you want on-chain discovery. +### How do I buy inference from another stack? + +```shell +obol buy inference https://seller.example/ +``` + +The command walks the seller's catalog, previews the cost, pre-signs payment authorizations from your agent's wallet, and publishes the remote model as `paid/` through your LiteLLM — your agents can then use it like any local model, with spend bounded by what you pre-authorized. See [Buying Services](buying-services.md). + ## Stack operations ### The cluster fails to start diff --git a/obol-stack/quickstart.md b/obol-stack/quickstart.md index 8dbb38c..73c4d7a 100644 --- a/obol-stack/quickstart.md +++ b/obol-stack/quickstart.md @@ -29,7 +29,7 @@ If you'd rather route through Anthropic or OpenAI, you can configure that with ` Run the bootstrap installer: ```shell -bash <(curl -s https://stack.obol.org) +bash <(curl -fsSL https://stack.obol.org) ``` The installer will: @@ -42,7 +42,7 @@ The installer will: {% tabs %} {% tab title="Default installation" %} ```shell -bash <(curl -s https://stack.obol.org) +bash <(curl -fsSL https://stack.obol.org) ``` Files are installed to: @@ -54,7 +54,7 @@ Files are installed to: {% tab title="Specific version" %} ```shell -OBOL_RELEASE=v0.9.0 bash <(curl -s https://stack.obol.org) +OBOL_RELEASE=v0.9.0 bash <(curl -fsSL https://stack.obol.org) ``` {% endtab %} @@ -137,9 +137,12 @@ Once you've watched a demo settle end-to-end, the same machinery lets you sell a ```shell obol sell inference my-model --model qwen3.5:9b --per-mtok 0.01 --token USDC --chain base obol sell http my-api --upstream my-svc --port 8080 --namespace my-ns \ - --per-request 0.001 --chain base --wallet + --per-request 0.001 --chain base --pay-to +obol sell agent my-analyst --price 0.05 --token USDC --chain base ``` +`sell agent` is the highest-margin shape — buyers pay for a whole specialised agent's replies (skills + memory + curated data), not just raw tokens. See [Agents & Skills](agents-and-skills.md) for building one worth paying for. + The mental model is: **anything in your cluster that exposes a Service can be wrapped in a `ServiceOffer` and gated behind x402**. The goal of v0.9 is to make that loop short enough that you can actually iterate on what's worth selling. See [Selling agent services](selling-services.md) for the full orientation on the three `sell` shapes (`http`, `inference`, `agent`), x402 economics, ERC-8004 registration, and marketplaces. @@ -155,7 +158,7 @@ Sellers receive `$OBOL` directly into their agent wallet. Read more about the [O `obol sell demo` skips on-chain registration by default (to avoid double-register reverts and the need for ETH on the agent wallet). When you're ready to be discoverable on a public agent registry: ```shell -obol sell register --chain mainnet --name my-service --private-key-file +obol sell register --chain mainnet --name my-service ``` This publishes the agent's wallet + service catalog to the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry on the chain you specify. @@ -215,6 +218,8 @@ obol stack purge -f # remove everything, including data * [Build a profitable Obol Stack](build-a-profitable-stack.md) — the end-to-end narrative: sync a bounded archive node, build an index, wrap it as a paid service, and turn it into a specialized agent business. * [Selling agent services](selling-services.md) — depth on the three `sell` shapes, x402 economics, and getting listed on marketplaces. +* [Buying services](buying-services.md) — rent a remote model with `obol buy inference`, or pay any x402 endpoint from your agent. +* [Agents & Skills](agents-and-skills.md) — create specialised sub-agents and see everything your agent can already do. * [Installing Networks](installing-networks.md) — sync local Ethereum / Aztec nodes (including bounded archives via `--since`). * [Installing Apps](installing-apps.md) — deploy any Helm chart. * [FAQ](faq.md) — common questions and troubleshooting. diff --git a/obol-stack/selling-services.md b/obol-stack/selling-services.md index 4b850f5..4f0d6a6 100644 --- a/obol-stack/selling-services.md +++ b/obol-stack/selling-services.md @@ -53,7 +53,7 @@ obol sell http my-index \ --per-request 0.001 \ --chain base \ --token USDC \ - --wallet 0x...your-wallet... + --pay-to 0x...your-wallet... ``` This is the path to take when **the value is in the data**: you've synced an archive node from a specific block, built an index on top, and you want to sell access to queries against it that no public RPC will serve. @@ -111,10 +111,7 @@ When quoting prices, name the unit explicitly — `0.01 OBOL / MTok`, `0.001 USD Buyers need to find you. The Obol Stack publishes an [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) agent registration document at `/.well-known/agent-registration.json` describing your services, supported payment methods, and endpoints. To list your agent on a public registry: ```shell -obol sell register \ - --chain mainnet \ - --name my-quant \ - --private-key-file ~/.config/obol/agents/my-quant/wallet.json +obol sell register --chain mainnet --name my-quant ``` This publishes your agent's wallet and service catalog to the ERC-8004 Identity Registry on the chain you specify. **Note that this requires ETH on the registering wallet for gas** — registration is not gas-sponsored. @@ -131,6 +128,19 @@ Once registered, several marketplaces and explorers index ERC-8004 registries an We do not recommend a single "official" marketplace — the agent-registry ecosystem is evolving fast, and the best strategy is to register on-chain and let multiple indexers pick you up. +### Brand your storefront + +Your tunnel hostname serves a public storefront landing page and a machine-readable catalog at `/api/services.json` (plus `/skill.md` for agent buyers). Make it look like a business, not a default install: + +```shell +obol sell info # buyer's-eye view: branding + every on-sale service +obol sell info my-quant # focus one service + how-to-buy +obol sell info set --display-name "Acme Labs" --tagline "Paid onchain analysis." --logo-url "https://…" +obol sell info reset # back to defaults +``` + +`obol sell info` shows exactly what buyers see — only operationally-ready offers appear. Operator-side health and conditions (including draining or not-ready offers) stay under `obol sell status`. After any change, run `sell info` and ask yourself: *would I buy from this storefront?* + ## Iterating on an agent business Selling the same agent forever at the same quality is leaving money on the table. The loop that compounds: @@ -156,6 +166,19 @@ obol sell delete my-quant --namespace my-ns Deletion removes the ServiceOffer CR, cascades the underlying Middleware and HTTPRoute via owner references, and deactivates the ERC-8004 registration (sets `active=false`). The agent's wallet and accumulated revenue are untouched. +### Surviving restarts + +Offers are persisted and replayed automatically: `obol stack up` re-publishes every offer after a reboot. To replay on demand — or to make it happen with nobody at the keyboard: + +```shell +obol sell resume # replay all persisted offers now +obol sell resume --install-boot-unit # Linux: install a systemd user unit that does it on boot +``` + +### Bonus shape: paid MCP tools + +`obol sell mcp [name]` runs a foreground x402-paid MCP server that forwards buyer JSON arguments to a backend HTTP service, injecting **your** API key server-side — the buyer pays per call and never sees the key. Useful for reselling metered access to an upstream API as an MCP tool. It's foreground-only: no ServiceOffer, and it is not replayed by `sell resume`. + ## Verifying your paths When you've shipped your first real (non-demo) offer, walk these checks: