From e2995f403e2b5896e81f90504c5e04e0ad97b208 Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 3 Aug 2026 13:23:24 +0100 Subject: [PATCH 1/5] docs: add Exa integration page (agent-driven API-credit purchases via card delegation) New integrations/exa.mdx between OpenClaw and BuildShip: the Exa partnership page detailing how agents buy and top up Exa API keys with x402 card delegation. Codeless format (prose contracts + SDK method anchors; the package typings are the call reference). Content blind-validated end to end with real purchases on both branches (owner-created delegation via discovery, and programmatic createDelegation fallback) on a fresh API key + latest SDK. Mintlify auto-serves the page as .md and auto-lists it in llms.txt via the docs.json navigation entry. --- docs.json | 1 + integrations/exa.mdx | 85 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 integrations/exa.mdx diff --git a/docs.json b/docs.json index a152869e..ce4aa2a5 100644 --- a/docs.json +++ b/docs.json @@ -148,6 +148,7 @@ "integrations/google-a2a", "integrations/nevermined-x402-ap2", "integrations/openclaw", + "integrations/exa", "integrations/buildship-integration" ] } diff --git a/integrations/exa.mdx b/integrations/exa.mdx new file mode 100644 index 00000000..aa57c8ba --- /dev/null +++ b/integrations/exa.mdx @@ -0,0 +1,85 @@ +--- +title: "Exa" +description: "Buy Exa API credits with card delegation: a $7 x402 purchase provisions or tops up an Exa API key, fully agent-driven." +icon: "magnifying-glass" +--- + +[Exa](https://exa.ai), the search engine built for AI, accepts autonomous agent payments through Nevermined's [x402 card-delegation](/specs/x402-card-delegation) scheme in production. An agent holding a Nevermined API key mints an x402 access token against Exa's payment plan and exchanges it at Exa's purchase endpoint for a working Exa API key; repeat purchases top up the same key. No human is needed at purchase time: the card owner authorizes spending once through a delegation, and the agent buys within that budget. + + + Exa's Nevermined plan ID:
`27800462147494506865542649899724877617306579171265399959488097895839186996870`
The purchase is for API credits, not for a single search request. \$7 covers roughly 1,000 standard searches; see [Exa pricing](https://exa.ai/pricing) for current rates. + + +## Prerequisites (one time, done by the card owner) + +1. Enroll a card at [nevermined.app](https://nevermined.app) → Payment Methods. +2. Create a **delegation** on the card: the spending permission an agent pays with. The owner sets the spending limit and duration, and can scope the delegation to a specific API key (recommended; it makes discovery deterministic for that key). +3. Generate an API key and give it to the agent. Two ways: + * **Embedded login flow (no copy/paste):** the agent hosts a callback on `127.0.0.1` and sends its human this URL to sign in: `https://nevermined.app/auth/cli?callback_url=http://127.0.0.1:/callback`. After sign-in, the browser redirects to the callback with `nvm_api_key=` for the agent to read. + * **Manual:** [nevermined.app](https://nevermined.app) → Account → API Keys → create a key and paste it to the agent (or open `https://nevermined.app/auth/cli` with no `callback_url` and copy the key shown on screen). + +**Agent-orchestrated alternative** (no dashboard navigation for the owner): an agent that already has an API key can run enrollment itself. Host a callback on `127.0.0.1`, then mint an embedded session: `POST https://api.live.nevermined.app/api/v1/embed/session` with `Authorization: Bearer ` and body `{ "returnUrl": "http://127.0.0.1:/callback" }`, which returns a `sessionToken`. Send the human this URL to enter their card in the browser: `https://embed.nevermined.app/cards/setup?sessionToken=&returnUrl=http://127.0.0.1:/callback&state=&provider=stripe`. When they finish, the browser redirects to the callback with `paymentMethodId` and `delegationId`; store the `delegationId`. The human still enters the card details and approves any bank step-up; the agent receives the resulting delegation directly. + +See the [x402 card-delegation spec](/specs/x402-card-delegation) for how enrollment and delegations work. + +## The flow + +Handled with the Nevermined Payments SDK (`npm install @nevermined-io/payments`; the package is ESM-only; in a fresh npm project set `"type": "module"` in `package.json`, or the import fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`). The package's bundled TypeScript definitions are the authoritative call reference for every method named below. For broader context, start from the [Payments overview](/products/payments/overview) and the [documentation index](https://nevermined.ai/docs/llms.txt). + +1. **Initialize** the SDK with your Nevermined API key only (`Payments.getInstance({ nvmApiKey })`). The environment is derived from the key prefix; do not pass an `environment` option. +2. **Find the delegation to pay with**; see [Getting a delegation](#getting-a-delegation) below. +3. **Mint the x402 access token** for the Exa plan ID via `payments.x402.getX402AccessToken`, using the `nvm:card-delegation` scheme and referencing the delegation by ID (`delegationConfig: { delegationId }`). No agentId is needed for this flow: the method's arguments are `(planId, agentId?, tokenOptions?)`, so pass the plan ID, `undefined`, and the token options. Tokens cannot create delegations on the fly; the delegation must exist first. +4. **POST the token to Exa** in the `payment-signature` header (endpoint below). The response contains the Exa API key. Check the HTTP status before reading the body. +5. **Use the key** against the standard [Exa Search API](https://docs.exa.ai). + +## Getting a delegation + +Query the delegations accessible to your API key with `payments.delegation.getPurchasingPower()` and select one with at least 700 cents of remaining budget. Budget fields are returned as strings, in cents. Purchasing-power results contain only delegations that can still pay; exhausted ones are excluded. With several delegations, discovery is deterministic when the owner key-scoped one to your key; to designate a specific budget among several, reference its ID explicitly. + +**If discovery returns none**, the preferred path is for the card owner to create a delegation in the dashboard (Prerequisites, step 2); the agent then re-runs discovery. Nothing needs to be copied. If no operator is reachable (or the request goes unanswered), a fully autonomous agent can create one programmatically with `payments.delegation.createDelegation`. Its payload fields: + +| Field | Value for this flow | +|---|---| +| `provider` | `"stripe"` | +| `providerPaymentMethodId` | The card's id from `payments.delegation.listPaymentMethods()` | +| `spendingLimitCents` | N × 700 for N expected purchases; a 700-cent delegation is exhausted after a single purchase | +| `durationSecs` | `3600` is a sensible default for a one-shot purchase; keep it short (least privilege) | +| `currency` | `"usd"` | + +The response includes the `delegationId` to mint with (it also includes a `delegationToken`; not needed for this flow; treat it as a secret and do not log it). **Card selection:** `listPaymentMethods()` carries no ordering guarantee and cards may be indistinguishable by metadata; if several are enrolled and the owner's intent is unknown, prefer asking the owner; otherwise any Active card of the provider is acceptable, and you should record which payment-method id was chosen. Note the trade-off of this whole path: the agent chooses the card and sets its own budget. Prefer an owner-created delegation whenever an owner is available. + +## Exa's purchase contract + +```bash +POST https://admin-api.exa.ai/team-management/nevermined/purchase-key +payment-signature: +``` + +* **Cost:** \$7 per purchase, charged to the card behind the delegation referenced by the token. +* **New payer:** `{ status: "ok", apiKey: "…", expiresAt: null }`; a new Exa API key with \$7 of credits. +* **Returning payer:** the same API key with \$7 more credits added. +* **Replayed token:** cached result, no new charge. +* **Missing/invalid signature:** `402 Payment Required` with payment requirements in the body. + +**When the key runs out:** Exa's regular API endpoints return `HTTP 402` with error tag `NO_MORE_CREDITS`. Mint a fresh x402 token with the same plan ID and delegation, POST it to the same endpoint, and Exa adds another \$7 of credits to the same key. + +## Verifying charges + +Use `payments.delegation.listDelegations()` to inspect spend per delegation (`amountSpentCents`, `transactionCount`, status). Fully spent delegations are marked `Exhausted` and no longer appear in `getPurchasingPower()` results; purchasing power lists only delegations that can still pay. + +## Troubleshooting + +| Symptom | Meaning / fix | +|---|---| +| Token mint fails: `Required token-generation input is missing or incomplete (HTTP 402)` | The mint referenced no existing delegation (e.g., legacy create-on-the-fly `delegationConfig` with card details). Create or discover a delegation first and pass `delegationConfig: { delegationId }`. | +| `ERR_PACKAGE_PATH_NOT_EXPORTED` on import | The SDK is ESM-only. Set `"type": "module"` in `package.json` or use `.mts`. | +| Console warning: `The 'environment' option is deprecated…` even though you never passed it | Known SDK issue; harmless. The environment is derived from your key prefix. | +| A delegation you spent from disappears from `getPurchasingPower()` | It is exhausted. Inspect it with `listDelegations()`; create or top up a delegation to continue. | +| Exa search returns `402` with `NO_MORE_CREDITS` | The Exa key's credits are spent. Repeat the purchase flow to top up the same key. | + +## References + +* [Payments overview](/products/payments/overview) +* [x402 card-delegation spec](/specs/x402-card-delegation) +* [Exa pricing](https://exa.ai/pricing) +* [Exa Search API](https://docs.exa.ai) From cb95b6da0ec95b8af64e5b3c15ff8c42a6886cfe Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 3 Aug 2026 13:25:22 +0100 Subject: [PATCH 2/5] docs(exa): drop agent-orchestrated enrollment paragraph pending prod verification The embed-session flow is documented on the staging agentic-instructions surface; live-environment support is unconfirmed beyond route existence. Re-add once verified on prod. --- integrations/exa.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/integrations/exa.mdx b/integrations/exa.mdx index aa57c8ba..de613bf3 100644 --- a/integrations/exa.mdx +++ b/integrations/exa.mdx @@ -18,8 +18,6 @@ icon: "magnifying-glass" * **Embedded login flow (no copy/paste):** the agent hosts a callback on `127.0.0.1` and sends its human this URL to sign in: `https://nevermined.app/auth/cli?callback_url=http://127.0.0.1:/callback`. After sign-in, the browser redirects to the callback with `nvm_api_key=` for the agent to read. * **Manual:** [nevermined.app](https://nevermined.app) → Account → API Keys → create a key and paste it to the agent (or open `https://nevermined.app/auth/cli` with no `callback_url` and copy the key shown on screen). -**Agent-orchestrated alternative** (no dashboard navigation for the owner): an agent that already has an API key can run enrollment itself. Host a callback on `127.0.0.1`, then mint an embedded session: `POST https://api.live.nevermined.app/api/v1/embed/session` with `Authorization: Bearer ` and body `{ "returnUrl": "http://127.0.0.1:/callback" }`, which returns a `sessionToken`. Send the human this URL to enter their card in the browser: `https://embed.nevermined.app/cards/setup?sessionToken=&returnUrl=http://127.0.0.1:/callback&state=&provider=stripe`. When they finish, the browser redirects to the callback with `paymentMethodId` and `delegationId`; store the `delegationId`. The human still enters the card details and approves any bank step-up; the agent receives the resulting delegation directly. - See the [x402 card-delegation spec](/specs/x402-card-delegation) for how enrollment and delegations work. ## The flow From 679514c2b097d6c90af2fb98215987f14a874d71 Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 3 Aug 2026 13:34:00 +0100 Subject: [PATCH 3/5] docs(exa): trim intro to the validated wording --- integrations/exa.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/exa.mdx b/integrations/exa.mdx index de613bf3..038b800b 100644 --- a/integrations/exa.mdx +++ b/integrations/exa.mdx @@ -4,7 +4,7 @@ description: "Buy Exa API credits with card delegation: a $7 x402 purchase provi icon: "magnifying-glass" --- -[Exa](https://exa.ai), the search engine built for AI, accepts autonomous agent payments through Nevermined's [x402 card-delegation](/specs/x402-card-delegation) scheme in production. An agent holding a Nevermined API key mints an x402 access token against Exa's payment plan and exchanges it at Exa's purchase endpoint for a working Exa API key; repeat purchases top up the same key. No human is needed at purchase time: the card owner authorizes spending once through a delegation, and the agent buys within that budget. +[Exa](https://exa.ai) accepts autonomous payments through Nevermined's [x402 card-delegation](/specs/x402-card-delegation) scheme. An agent holding a Nevermined API key mints an x402 access token against the Exa plan and exchanges it at Exa's purchase endpoint for a working Exa API key. Repeat purchases top up the same key. Exa's Nevermined plan ID:
`27800462147494506865542649899724877617306579171265399959488097895839186996870`
The purchase is for API credits, not for a single search request. \$7 covers roughly 1,000 standard searches; see [Exa pricing](https://exa.ai/pricing) for current rates. From c3c9c3c78fb4b3fa9074571c5cf8cabf7b52d923 Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 3 Aug 2026 13:35:11 +0100 Subject: [PATCH 4/5] docs: repoint api-providers Exa reference from the stale exa.ai mirror to the new integrations/exa page --- solutions/api-providers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/api-providers.mdx b/solutions/api-providers.mdx index 4e39c106..918d5ffb 100644 --- a/solutions/api-providers.mdx +++ b/solutions/api-providers.mdx @@ -12,7 +12,7 @@ Nevermined turns that failure mode into revenue with a small server-side integra [**Exa**](https://exa.ai) is the live reference. Agents pay Exa \$7 via a Nevermined-delegated card and receive an Exa API key with \$7 of credits. When the key runs out, the agent tops up through the same endpoint. Same key, more credits, no human touched it. -- Exa integration mirror: [exa.ai/docs/integrations/nevermined.md](https://exa.ai/docs/integrations/nevermined.md) +- Exa integration guide: [/integrations/exa](/integrations/exa) ## What you build, in five steps From 0054c8f3aa23ee2f68fa40ac8568c0355922fd56 Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 3 Aug 2026 13:37:14 +0100 Subject: [PATCH 5/5] docs: remove last link to Exa's stale integration mirror --- solutions/api-providers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/api-providers.mdx b/solutions/api-providers.mdx index 918d5ffb..622d2320 100644 --- a/solutions/api-providers.mdx +++ b/solutions/api-providers.mdx @@ -386,7 +386,7 @@ Agents don't read your HTML. They read your `llms.txt` and the `.md` mirrors nex Plain-text markdown skeleton with placeholders. Drop it wherever your docs live and fill in your plan ID, endpoint, and response shape. - Live example: [Exa's `/docs/integrations/nevermined.md`](https://exa.ai/docs/integrations/nevermined.md). + Live example of the full flow: the [Exa integration guide](/integrations/exa).