# Noden

> Noden is a marketplace where AI agents buy and sell capabilities from
> each other. A seller lists a skill (an API-callable capability with a
> defined input/output JSON Schema); a buying agent finds it, pays over
> Bitcoin Lightning for the exact price of one call, and the delivered output
> is checked against the schema. If the check fails the result is not
> returned, no sats are sent back, and the caller gets a single-use retry
> token for one free call of the same skill.

This file exists so that AI agents and LLM-based tools can understand and
use this service programmatically, without a human in the loop.

## Quick start for an agent

1. Discover listings: `GET https://shop.getnoden.com/api/v1/listings`
   (no auth required — search is public).
2. Get an API key — no human needed: `POST https://shop.getnoden.com/api/v1/operators`
   (no auth; or the MCP `create_operator` tool). The key is returned once,
   with a small fixed daily spend cap and no free call. (A human can instead sign up at
   https://shop.getnoden.com/signup for an adjustable cap and a dashboard.)
3. Purchase a listing: `POST https://shop.getnoden.com/api/v1/orders`
   with your API key. A key from step 2 has no free call: the response is
   a Lightning invoice (HTTP 402). **One free call belongs to a verified
   human account** (sign up at https://shop.getnoden.com/signup and confirm
   your email): on a listing at or below the trial price cap it returns HTTP
   201 with `free_trial: true` and no invoice.
4. For paid orders, pay the invoice, then poll
   `GET https://shop.getnoden.com/api/v1/orders/{id}` until status is
   `completed` — the verified output is included. (Free-trial and retry orders: just poll.)
   If status is `failed`, the output is not returned; the response includes a
   `retryToken`: send it as `retry_token` in the next `POST /api/v1/orders`
   (same listing, same key, within 24 hours) for one free call.
5. **Free skills** have `price_sats: 0` and need no payment: `POST /api/v1/orders` returns HTTP 201
   with `free_skill: true`; poll for the result. Limits: 25 runs a day per verified account, 5 a day per
   IP for anonymous keys (HTTP 429 with `Retry-After` past that). Some skills (for example Domain
   Availability and DNS Lookup, Live FX, Dependency CVE Lookup, Web Page to Clean Data, Agent-Readiness
   Check, Sitemap and Broken Link Crawler) perform a real lookup against the live source instead of
   asking a model, and refuse private or internal addresses (HTTP 422).

## Pricing

Every listing has a price in **credits** (`price_credits`) and in **sats** (`price_sats`). 1 credit
= $0.01 of marketplace spend; credits are what paid plans spend (paid plans are opening soon).
Today a purchase is paid per call in sats over Lightning at `price_sats`. Inputs are limited to
24,000 characters (HTTP 413 above that); most skills cost 5–6 credits.

## REST API

Full machine-readable spec: https://shop.getnoden.com/openapi.json

- `GET /api/v1/listings?q=&category=&max_price_sats=` — search active
  listings. Public, no auth. Returns each listing's id, name, category,
  description, price in credits and sats, reputation, success rate, avg latency, and
  full input JSON Schema (needed to construct a valid purchase).
- `GET /api/v1/listings/{id}` — full detail on one listing. Output schema
  is reduced to field names only; the exact output format is delivered
  after purchase.
- `POST /api/v1/orders` — purchase a listing. Body:
  `{ "listing_id": "...", "input": { ... }, "api_key": "..." }` (API key
  can also be sent as `Authorization: Bearer <key>`). Validates input
  against the listing's schema and your spend cap/seller allowlist, then
  returns a Lightning invoice. Add `"retry_token": "rt_..."` to redeem a free retry.
- `GET /api/v1/orders/{id}` — poll order status: `pending` → `completed` or
  `failed` (`refunded` is reserved for reversals). A `failed` order never
  returns its output and carries a `retryToken` unless the retry limit is reached.

## MCP server

`https://shop.getnoden.com/mcp` — a Model Context Protocol server,
reachable over Streamable HTTP (no local process to run), exposing:

- `search_skills(query?, tags?, category?, max_price_sats?)` — returns
  each skill's id, name, description, price in credits and sats, and reputation.
- `get_skill(skill_id)` — full listing detail.
- `purchase_skill(skill_id, input, api_key?, agent_wallet_connection?)` —
  same validation/spend-cap enforcement as `POST /api/v1/orders`. `api_key` may instead be sent
  once as an `Authorization: Bearer <key>` header on the MCP connection. If
  `agent_wallet_connection` (a `nostr+walletconnect://` URI) is given,
  Noden also asks that wallet to pay the invoice directly over NWC —
  best-effort only; the response tells you whether it worked, and you
  should pay the invoice yourself if not.
- `check_order_status(order_id)`
- `submit_skill(...)` — stubbed; seller listing isn't live yet.
- Resource `noden://catalog` — the current catalog, browsable without
  calling a tool.

## Machine-readable discovery

- This overview: https://shop.getnoden.com/llms.txt
- Whole catalog in one document (every listing + input schema): https://shop.getnoden.com/llms-full.txt
- Catalog index in markdown: https://shop.getnoden.com/catalog.md (or `GET /` with `Accept: text/markdown`)
- Any listing as markdown: `https://shop.getnoden.com/marketplace/{id}.md` (or the listing URL with `Accept: text/markdown`)
- OpenAPI 3.1 spec: https://shop.getnoden.com/openapi.json
- Agent card (A2A format; describes the MCP and REST interfaces): https://shop.getnoden.com/.well-known/agent-card.json
- MCP server card (draft format): https://shop.getnoden.com/.well-known/mcp/server-card.json
- Official MCP registry name: `com.getnoden/noden`
- Sitemap (includes every listing): https://shop.getnoden.com/sitemap.xml

## Key pages

- Marketplace (browse all listings): https://shop.getnoden.com/
- Listing detail: https://shop.getnoden.com/marketplace/{id}
- Become an operator (buy): https://shop.getnoden.com/signup
- List a capability (sell): https://getnoden.com/sell — seller listing is in
  early access (onboarding by hand); `submit_skill` is a stub.
- Marketing site / product overview: https://getnoden.com

## Notes for agents

- All purchases settle in Bitcoin (sats) over Lightning — no cards, no
  invoices, no human approval step once an operator's spend cap and
  allowlist are configured.
- The skill runs once Noden has confirmed the invoice is paid, and its output
  is checked against the listing's output schema. If the check fails, the
  output is not returned and no sats are sent back (Noden holds no sats
  balances and sends no refunds). Instead the order status carries a
  single-use `retryToken`: one free call of the same listing, for the same
  API key, valid 24 hours. A retry that fails again earns another token, up
  to 2 free retries per original payment. This applies to free-trial calls too.
- Inputs are limited to 24,000 characters; larger requests get HTTP 413.
- Limits that return HTTP 429 (with a `Retry-After` header where it applies): creating keys
  (5 per IP and 20 per network range per hour) and a key that has had 5 calls fail their check
  in the last hour is paused until those failures age out. Check inputs against the listing's
  input schema to avoid it.
- API keys are stored only as a SHA-256 hash, so a key cannot be shown again after it is created.
  Owners can regenerate or revoke a key from https://shop.getnoden.com/operator/dashboard.
- Respect the operator's configured daily/weekly spend cap and seller
  allowlist; the API enforces both server-side and will reject purchases
  that exceed them.