metered-data-fetch — paid data APIs, one key, quote before every call

Session (auto — never dead-stop on auth): before your first settlemesh call, run settlemesh whoami; if it errors and SETTLE_API_KEY is unset, run settlemesh login yourself — it opens the browser for a one-time human approval, polls until approved, and caches the session. Do NOT stop to ask the user to "log in manually" — drive it. Keep an explicit human confirmation only for spending / credential-lending actions (fail-closed).

Every "give your agent web search / scraping / SEO data" skill ends the same way: "get an API key from each data vendor and paste it here." Now you own an account per vendor, a key in an env file, and a bill you can't see until the invoice lands. SettleMesh replaces all of them with one key and a quote before every call. You search a single catalog, read the exact Aev a call will cost, then run it — metered per-call, no provider signup, no BYOK.

A prompt-only skill can't do this: it can only wrap a key you already own, so it can't quote a price, can't meter per-call, and can't front you a free first try. Here the bill follows the work — quote up front, per-capability metering, and a free first call to every capability.

Setup (once)

1. npm install -g settlemesh@latest
2. settlemesh login (a human approves once in the browser) — or set SETTLE_API_KEY=sk-settle-... for headless/CI.

Discover → inspect → quote → call

Never memorize provider endpoints. Search the catalog for the task, read the tool's input schema, quote the exact call, then call it.

# 1. Discover the right tool by task (not by provider name):
settlemesh search "web search" --json
settlemesh search "SEO SERP" --json          # SERP/rankings capability id — DISCOVER it, don't hardcode
settlemesh capabilities search "stock price" --json

# 2. Inspect the contract before you spend:
settlemesh tool show web.search --json
settlemesh tool schema web.search            # exact input fields

# 3. Quote — read-only cost ceiling in Aev, no hold, no charge:
settlemesh quote web.search --input '{"q":"SettleMesh"}' --json

# 4. Call it:
settlemesh tool call web.search --input '{"q":"SettleMesh"}' --json

Add --confirm for costly or side-effecting calls and --wait to poll an async job:

settlemesh tool call web.scrape --input '{"url":"https://example.com"}' --confirm --json

Real capability families: web search + scrape, finance/market data (finance.stocks.search / .quote / .daily), SEO/SERP (DataForSEO-backed — the id can vary, so find it with settlemesh search "serp" --json, don't hardcode), and LLMs (llm.chat). One key, one unit, one catalog.

Notes

• First call to each official capability is FREE — no card, and refunded if it fails — so an agent can try many distinct data APIs before funding anything. Only repeat calls draw down your balance.
• The exact Aev billed is on the X-Settle-Charged-Aev response header (HTTP path); the CLI prints the charge. A failed call never charges you — retries are safe.
• Everything is billed in Aev (1 USD = 100 Aev). Check balance with settlemesh aev balance; itemized charges are in settlemesh aev ledger --limit 5.
• The edge: a quote before every call, first-call-free per capability, and being able to stack these paid calls directly onto a deployed, end-user-paying app — see charge-my-users to make your users' wallets pay for the data your app fetches, with your markup.