diff --git a/docs.json b/docs.json index d2f66155..147637d3 100644 --- a/docs.json +++ b/docs.json @@ -36,6 +36,15 @@ { "tab": "Guides", "groups": [ + { + "group": "Use Cases", + "pages": [ + "docs/use-cases/overview", + "docs/use-cases/monetize-paid-apis-for-agents", + "docs/use-cases/agent-discoverability", + "docs/use-cases/case-study-exa" + ] + }, { "group": "Learn", "pages": [ @@ -368,6 +377,14 @@ "source": "/docs/solutions/", "destination": "/docs/solutions/agent-to-agent-monetization" }, + { + "source": "/docs/use-cases", + "destination": "/docs/use-cases/overview" + }, + { + "source": "/docs/use-cases/", + "destination": "/docs/use-cases/overview" + }, { "source": "/docs/integrations", "destination": "/docs/integrations/mcp" diff --git a/docs/use-cases/agent-discoverability.mdx b/docs/use-cases/agent-discoverability.mdx new file mode 100644 index 00000000..04423135 --- /dev/null +++ b/docs/use-cases/agent-discoverability.mdx @@ -0,0 +1,193 @@ +--- +title: "Agent discoverability" +description: "Make your paid API findable by autonomous agents using the llms.txt convention and a Nevermined integration page. Copy-paste templates included." +icon: "satellite-dish" +--- + +A paid API integration only works if agents can *find* it without a human pointing the way. Today the de facto convention is the [llms.txt](https://llmstxt.org) file: a static `llms.txt` at the root of your docs site that lists, in plain Markdown, the resources you want LLMs to know about. + +Exa proved this works in production. Their `llms.txt` has a single line under `## Integrations` pointing to `nevermined.md`, and that's it — every agent that reads their docs index now knows the Nevermined integration exists, what it costs, and how to invoke it. This page covers how to do the same for your service. + +## The two files you need + + + + Add an `## Integrations` section (if you don't have one) and a single line linking to your Nevermined integration page. That's the entry point — every LLM-aware crawler that reads your `llms.txt` will follow this link. + + + A short Markdown page describing how an agent should pay for and use your service. Structure it the same way Exa does so agents that have already seen one integration page can navigate yours without surprises. + + + +## What goes in `nevermined.md` + +Six sections, in this order: + +| Section | Why it's there | +| --- | --- | +| Intro | One sentence: what your service does, what the integration enables. | +| Buy a key | The endpoint URL + the `payment-signature` header. The "API surface" of the integration. | +| What \$X buys | Pricing table mapping the plan price to concrete units in your product (e.g. "1000 searches", "10,000 documents"). | +| Sample request | A complete, copy-pasteable TypeScript snippet. The reference for any agent that needs to generate code. | +| Parameters you get from Nevermined | Plan ID, scheme (`nvm:card-delegation`), spending limit, network — the concrete values an agent needs to substitute in. | +| When the key runs out | The HTTP 402 response shape (status code, error tag, message). Agents must key off `tag: "NO_MORE_CREDITS"`, not your human-readable error string. | +| References | Links to your full API docs, Nevermined docs, x402 spec. | + +## Copy-paste template + +The same templates ship inside the [`web-search-paid-api-ts`](https://github.com/nevermined-io/tutorials/tree/main/web-search-paid-api-ts/src/llms-txt-template) tutorial under `src/llms-txt-template/`. Pull them from there if you'd rather grab the raw files. + +### `llms.txt` (root of your docs site) + +```text +# {{SERVICE_NAME}} + +> {{ONE_SENTENCE_DESCRIPTION}}. AI agents can buy access autonomously via Nevermined — no human onboarding required. + +## Docs + +- [API reference]({{API_REFERENCE_URL}}): every endpoint, with request and response shapes. +- [Getting started]({{QUICKSTART_URL}}): the human-facing onboarding path. + +## Integrations + +- [Nevermined]({{NEVERMINED_INTEGRATION_MD_URL}}): autonomous agent payments. A {{PRICE_USD}} purchase provisions or tops up a {{SERVICE_NAME}} API key with {{QUOTA_PER_PURCHASE}} requests. One endpoint, one card charge, no metering changes on the provider side. + +## Optional + +- [Pricing]({{PRICING_URL}}) +- [Status page]({{STATUS_URL}}) +``` + +### `nevermined.md` (next to your other integration docs) + +````markdown +# Nevermined + +Autonomous agent payments for {{SERVICE_NAME}} via Nevermined x402 card delegation. A {{PRICE_USD}} purchase provisions or tops up a {{SERVICE_NAME}} API key with {{QUOTA_PER_PURCHASE}} requests. + +## Buy a key + +``` +POST {{PURCHASE_ENDPOINT_URL}} +payment-signature: +``` + +Pay with a credit card enrolled in [Nevermined](https://nevermined.app). One successful POST = one card charge of {{PRICE_USD}}. The response contains a {{SERVICE_NAME}} API key you can use against the regular endpoints. + +## What {{PRICE_USD}} buys + +| Endpoint | Cost per call | Calls per purchase | +| --- | --- | --- | +| `{{ENDPOINT_A_PATH}}` | 1 request | {{QUOTA_PER_PURCHASE}} | +| `{{ENDPOINT_B_PATH}}` | {{ENDPOINT_B_COST}} requests | {{ENDPOINT_B_CALLS}} | +| `{{ENDPOINT_C_PATH}}` | {{ENDPOINT_C_COST}} requests | {{ENDPOINT_C_CALLS}} | + +Provider-side metering. Independent of any Nevermined credit balance. + +## Sample request + +```typescript +import { Payments } from '@nevermined-io/payments' + +const PLAN_ID = '{{NEVERMINED_PLAN_ID}}' + +const payments = Payments.getInstance({ + nvmApiKey: process.env.NVM_API_KEY!, + environment: 'live', +}) + +// 1. Mint an x402 token scoped to an enrolled card. +const { accessToken } = await payments.x402.getX402AccessToken(PLAN_ID, undefined, { + scheme: 'nvm:card-delegation', + delegationConfig: { + providerPaymentMethodId: 'pm_...', // Stripe payment method enrolled in Nevermined + spendingLimitCents: {{PRICE_CENTS}}, // >= the plan price + durationSecs: 3600, + }, +}) + +// 2. Exchange the token for (or top up) an API key. +const res = await fetch('{{PURCHASE_ENDPOINT_URL}}', { + method: 'POST', + headers: { 'payment-signature': accessToken }, +}) +const { apiKey } = await res.json() + +// 3. Use the key against the normal {{SERVICE_NAME}} endpoints. +const search = await fetch('{{REGULAR_ENDPOINT_URL}}', { + method: 'POST', + headers: { 'x-api-key': apiKey, 'content-type': 'application/json' }, + body: JSON.stringify({ query: 'agentic payments' }), +}) +``` + +## Parameters you get from Nevermined + +| Field | Value | Where to find it | +| --- | --- | --- | +| Plan ID | `{{NEVERMINED_PLAN_ID}}` | Listed above; or look up your plan on https://nevermined.app | +| Scheme | `nvm:card-delegation` | Fixed for this integration | +| Spending limit | At least `{{PRICE_CENTS}}` cents | Must cover one purchase | +| Network / environment | `live` (or `sandbox` for testing) | Match the environment the plan was created in | + +## When the key runs out + +When the API key's quota is exhausted, regular endpoints return HTTP 402 with: + +```json +{ + "tag": "NO_MORE_CREDITS", + "error": "API key has no remaining requests. Top up by calling {{PURCHASE_ENDPOINT_URL}}." +} +``` + +To top up, call `POST {{PURCHASE_ENDPOINT_URL}}` again with a fresh x402 token. The same card is charged, the same API key is returned with {{QUOTA_PER_PURCHASE}} additional requests credited. + +Agents should key off `tag: "NO_MORE_CREDITS"`, not the human-readable `error` string — the wording may vary between providers, the tag is the stable contract. + +## References + +- {{SERVICE_NAME}} API docs: {{API_REFERENCE_URL}} +- Nevermined docs: https://docs.nevermined.io +- x402 specification: https://github.com/coinbase/x402 +- Nevermined x402 module (TypeScript): https://docs.nevermined.io/docs/api-reference/typescript/x402 +```` + +## Where to host the files + +| File | Hosting location | Why | +| --- | --- | --- | +| `llms.txt` | Root of your docs site, e.g. `https://yourservice.example/docs/llms.txt` | The llms.txt convention says "at the root". Crawlers look there first. | +| `nevermined.md` | Next to your other integration docs, e.g. `https://yourservice.example/docs/integrations/nevermined.md` | URL must be stable — the `llms.txt` entry references it by absolute URL. | + +If your docs site doesn't already publish `.md` mirrors next to your HTML pages, you'll need to add that. Mintlify-based sites get it automatically; for other doc tools the easiest path is dropping the file in `public/` or whatever your static-asset folder is called. + +## Test it before agents see it + + + + `curl https://yourservice.example/docs/llms.txt` and `curl https://yourservice.example/docs/integrations/nevermined.md` should both return 200 with the expected content. No JavaScript redirects, no auth walls. + + + Run the TypeScript snippet in your `nevermined.md` against your real endpoint, using a sandbox plan. If your own copy-paste doesn't work, no agent's will either. + + + Paste your `llms.txt` URL into Claude, ChatGPT, or any agent that supports web fetching, and ask: *"I want to use `{{SERVICE_NAME}}`. Read the llms.txt and explain how an agent would pay for and use this service."* The summary should match what you actually built — if it doesn't, your `nevermined.md` is ambiguous. + + + +## Known agent rakes + +Tips collected from running real agents against real integration pages. This list will grow as we validate more agents against the pattern. + + + This section will be populated after the multi-agent validation pass that follows [nevermined-io/nvm-monorepo#1684](https://github.com/nevermined-io/nvm-monorepo/issues/1684). For now, the [test it before agents see it](#test-it-before-agents-see-it) checklist above covers the basics. + + +## Related + +- [Monetize paid APIs for agents](/docs/use-cases/monetize-paid-apis-for-agents) — the use case this discoverability layer plugs into +- [API Providers — implementation guide](/docs/solutions/api-providers) — the server-side handler this integration page describes +- [llms.txt specification](https://llmstxt.org) — the broader convention +- [Exa's live `llms.txt`](https://exa.ai/docs/llms.txt) and [`nevermined.md`](https://exa.ai/docs/integrations/nevermined.md) — production reference diff --git a/docs/use-cases/case-study-exa.mdx b/docs/use-cases/case-study-exa.mdx new file mode 100644 index 00000000..84672023 --- /dev/null +++ b/docs/use-cases/case-study-exa.mdx @@ -0,0 +1,78 @@ +--- +title: "Case study: Exa" +description: "How Exa shipped autonomous-agent payments with one endpoint, no metering changes, and a static llms.txt entry — and what it means for monetizing any paid API." +icon: "star" +--- + +[Exa](https://exa.ai) is a search API used by AI agents to retrieve content from the web. Their integration with Nevermined is the live reference for the **monetize paid APIs for agents** pattern — and it works because every part of it was designed to need as little new infrastructure as possible. + +## What Exa built + +One new endpoint. That's the whole server-side delta. + +| Field | Value | +| --- | --- | +| Endpoint | `POST https://admin-api.exa.ai/team-management/nevermined/purchase-key` | +| Auth | `payment-signature` header carrying an x402 access token | +| Price | \$7 per purchase, charged via Nevermined card delegation (`nvm:card-delegation` scheme) | +| Response | `{ "status": "ok", "apiKey": "...", "expiresAt": null }` | +| Top-up | Same endpoint, same payer wallet → existing key tops up instead of issuing a new one | +| When exhausted | Regular Exa endpoints return HTTP 402 + `{ "tag": "NO_MORE_CREDITS" }` | + +What \$7 buys, per their integration page: + +| Endpoint type | Calls per \$7 | +| --- | --- | +| Standard search | ~1,000 | +| Deep-Lite search | ~700 | +| Content pages | ~7,000 | +| Deep-Reasoning | ~466 | + +Notice: Exa is doing all the metering. The \$7 from Nevermined is just the trigger that funds an internal balance. Search rate-limits, deep-reasoning quotas, and every other product decision stays inside Exa's existing systems — Nevermined never touches the hot path. + +## Why this is strategically interesting for Nevermined + +Most of what Nevermined had been doing before this is monetizing **agents** — paywalling the AI service itself, charging per call. Exa flips the angle: now Nevermined is monetizing **what agents pay for to do their job**. + +That's a much wider surface. Every agent that runs end-to-end consumes paid services along the way — search, document retrieval, image generation, market data feeds, maps, weather, financial APIs. Each of those is a potential Exa-shaped integration. And because the provider-side cost is so low (one endpoint, no metering changes), the pattern travels well. + +> "We're no longer just monetizing the agents themselves — we're monetizing paid services that agents may need to complete their task. And best of all the integration is really simple." + +## How agents discover the integration + +Exa's [llms.txt](https://exa.ai/docs/llms.txt) lists their Nevermined integration under `## Integrations` — a single line linking to a static [`nevermined.md`](https://exa.ai/docs/integrations/nevermined.md). That's the entire discovery surface. Any agent that reads the `llms.txt` (and most LLM-powered tools that fetch URLs do) follows the link, reads the integration page, and now knows how to pay for and use Exa. + +The integration page itself is six sections: intro / buy a key / what \$7 buys / sample request / parameters from Nevermined / when the key runs out / references. Nothing more. The structure is so small that any LLM-class agent can ingest it as part of normal context and act on it without special prompting. + +[How to publish your own llms.txt + nevermined.md →](/docs/use-cases/agent-discoverability) + +## What this means for other providers + +If you're an API provider with existing metering, the takeaways: + + + + One purchase endpoint, no per-call settlement, no SDK on your hot path. The handler is the same shape regardless of which card rail (Stripe / Braintree / Visa Trusted Agent Protocol) the buyer enrolled. + + + Exa kept their internal metering, their rate limits, their tier structure. Nevermined just adds a new top-up trigger. You can offer the same product to humans and to agents with no fork in the codebase. + + + No agent registry to maintain, no API to call. A `llms.txt` + a `nevermined.md` on your existing docs site is the whole thing. + + + Exa's integration page mirrors a structure you can adopt verbatim — same section headings, same fields. Agents that have seen one will navigate yours. + + + +## Try it yourself + +The [`web-search-paid-api-ts`](https://github.com/nevermined-io/tutorials/tree/main/web-search-paid-api-ts) tutorial implements the Exa pattern end-to-end against a stub web-search service. Server, client, llms.txt + nevermined.md templates, README walkthrough. Clone it, point it at a sandbox PAYG plan, and you'll have an agent autonomously buying an API key in under five minutes. + +## Related + +- [Exa's live integration page](https://exa.ai/docs/integrations/nevermined.md) +- [Exa's `llms.txt`](https://exa.ai/docs/llms.txt) +- [Monetize paid APIs for agents](/docs/use-cases/monetize-paid-apis-for-agents) — the pattern this case study ships +- [Agent discoverability](/docs/use-cases/agent-discoverability) — how to publish your own integration page +- [API Providers — implementation guide](/docs/solutions/api-providers) — the technical deep-dive diff --git a/docs/use-cases/monetize-paid-apis-for-agents.mdx b/docs/use-cases/monetize-paid-apis-for-agents.mdx new file mode 100644 index 00000000..3aa47588 --- /dev/null +++ b/docs/use-cases/monetize-paid-apis-for-agents.mdx @@ -0,0 +1,73 @@ +--- +title: "Monetize paid APIs for agents" +description: "Sell access to your API to autonomous agents with one x402-protected endpoint. The agent pays, you return an API key, your existing metering takes over. Live with Exa." +icon: "key" +--- + +Most APIs already have keys, quotas, and rate limits. What they don't have is a way for an AI agent to buy access **without a human in the loop** — no Stripe Checkout, no signup form, no API console. + +This use case wires that missing piece in with a single new endpoint on your side. Agents pay through Nevermined x402, you mint or top up an API key, and the rest of your stack — metering, rate limits, billing analytics — keeps working exactly as it did before. + +## What it looks like in production + +[**Exa**](https://exa.ai) is the live reference. Agents POST a Nevermined-issued x402 token to `https://admin-api.exa.ai/team-management/nevermined/purchase-key` — \$7 is charged on a delegated card, Exa returns an API key with \$7 of credits, and the agent uses that key against the regular Exa search endpoints. When the key runs out, the agent calls the same purchase endpoint again. Same key, more credits, no human touched it. + +The whole integration on Exa's side: one endpoint, zero changes to their existing metering. + +- [Exa integration page](https://exa.ai/docs/integrations/nevermined.md) — the live `nevermined.md` agents discover +- [Exa case study](/docs/use-cases/case-study-exa) — the story, the numbers, what worked + +## When to pick this pattern + + + + - You already have an API with its own keys, quotas, rate limits + - One purchase maps to a fixed unit (e.g. \$7 → 10K requests) + - You want integration cost to be a single new endpoint + - You'd rather not change how you bill on the hot path + + + - You don't have your own metering yet + - Per-call settlement with variable cost matches your product + - You want Nevermined to handle quota tracking end-to-end + - See [Charge credits](/docs/integrate/patterns/charge-credits) and [Validate requests](/docs/integrate/patterns/validate-requests) + + + +Both patterns ride the same x402 protocol. They differ only in *where* in the request flow the payment happens — at purchase time (this page) or at every call (`http-simple-agent-ts` style). + +## Build it + +The full technical guide — server-side handler in TypeScript, Python, and raw HTTP, plus the optional middleware variant — lives on the **API Providers** solutions page. + + + 5-step flow, code samples, idempotency notes, FAQ. Start here when you're ready to wire it up. + + +For a runnable end-to-end example you can clone today: + + + Express server with `/purchase-key` + `/search` that mirrors the Exa pattern against a stub web-search service. Uses the facilitator API directly (not the middleware) so the verify → settle → provision flow is visible. Ships with a copy-paste `llms.txt` + `nevermined.md` template. + + +## Make it agent-discoverable + +A paid API only works for agents if they can *find* the integration on their own. Convention, lifted from Exa: publish a static `llms.txt` at your docs root that links to a `nevermined.md` integration page. Any LLM that knows the [llms.txt](https://llmstxt.org) convention can then read, understand, and act on the integration without you doing anything else. + + + How to publish a `llms.txt` + `nevermined.md` that agents will pick up. Includes a copy-paste template. + + +## A note on the redemption ordering + +When you implement the handler, the safe ordering is **verify → settle → provision**. Verify checks the token, settle moves the money, provisioning the key happens *last* because it's local and easy to make idempotent on retry. If settle fails, no key has been issued — the customer is neither charged nor served. Cleaner outcome than provisioning first and then discovering the settle failed. + +This isn't a footnote — getting the ordering wrong leaks quota on declined cards. The tutorial linked above implements it correctly; the deeper [solutions page](/docs/solutions/api-providers) walks through the steps in detail. + +## Related + +- [API Providers — implementation guide](/docs/solutions/api-providers) +- [Agent discoverability](/docs/use-cases/agent-discoverability) +- [Case study: Exa](/docs/use-cases/case-study-exa) +- [Exa's live integration page](https://exa.ai/docs/integrations/nevermined.md) +- [Nevermined x402 protocol overview](/docs/development-guide/nevermined-x402) diff --git a/docs/use-cases/overview.mdx b/docs/use-cases/overview.mdx new file mode 100644 index 00000000..a5ba78a1 --- /dev/null +++ b/docs/use-cases/overview.mdx @@ -0,0 +1,27 @@ +--- +title: "Use Cases" +description: "Productized patterns that monetize what agents do, what they consume, and what they unlock. Start here if you're deciding what to build with Nevermined." +icon: "compass" +--- + +Solutions tell you *what's possible*. Use cases tell you *what someone shipped*. Each page in this section walks through a real, productized pattern — what it monetizes, when to pick it, who's already running it, and the integration cost. + +If you're scoping a Nevermined integration and want to know "is this the right shape for what I'm building?", start here. + + + + One x402-protected endpoint hands out a quota-bearing API key. The provider keeps their own metering, no per-call settlement. Live in production with [Exa](https://exa.ai/docs/integrations/nevermined.md). Best when your service already has API keys with quotas. + + + +## Why "Use Cases" is a separate section + +Nevermined started by monetizing **agents** — letting builders charge for the AI services they expose. But the same primitives also monetize **what agents pay for to get their job done**: third-party APIs, MCP tools, data feeds, anything an agent needs mid-task that a human would have paid for in a browser. + +That second class of integration looks different on the wire — often one purchase endpoint and the provider's existing metering everywhere else — and it deserves its own home in the docs. More use cases will land here as the patterns get productized. + +## Related + +- [Solutions](/docs/solutions/api-providers) — the technical implementation guides behind each use case +- [Payment patterns](/docs/integrate/patterns/fiat-payments) — the lower-level building blocks +- [Nevermined x402](/docs/development-guide/nevermined-x402) — the protocol everything sits on