ronin-buyer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RONIN ZERO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,14 @@
+RONIN buyer integration is a clean implementation of public protocol and framework contracts.
+No Agent402 server, adapter source, identity, wallet, credentials or private state is included.
+Agent402 is a trademark of its owner and is used only when identifying the external index.
+The MIT license in this directory applies only to this integration package, not the RONIN seller repository.
+Third-party dependencies retain their own licenses. @x402/core and @x402/evm implement the x402 protocol;
+@modelcontextprotocol/sdk implements the MCP transport. Framework adapters use the public framework APIs.
+
+Architecture references (accessed 2026-09-12):
+https://github.com/MikeyPetrillo/Agent402
+https://agent402.tools/docs/x402-Index-and-Router
+https://github.com/coinbase/agentkit
+https://modelcontextprotocol.io/docs/develop/build-server
+https://docs.openclaw.ai/plugins/building-plugins
+https://developers.openai.com/api/docs/guides/function-calling

package/README.md

@@ -0,0 +1,129 @@
+# RONIN Web Research — native buyer tool
+
+Install `ronin_web_research` in a buyer agent to search the web, retrieve sources and verify research claims. The tool knows its production URL, handles x402 `402 → authorization → one retry`, and returns the full RONIN result plus receipt. **0.010000 USDC per call, on Base.** Installing this package is free; research calls are paid.
+
+Production resource: `https://seller.agratys.website/machine-services/search-router`.
+Network `eip155:8453`; canonical USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`;
+recipient `0xaD1dedD19cC97C54509F63B3ad03259de3Fb7D26`; atomic amount `10000`.
+EIP-712 token domain: `USD Coin`, version `2`. A challenge advertising the ticker `USDC` as the domain name is rejected before signing; the actual Base token uses `USD Coin`.
+
+## Install the versioned release
+
+Node 20.18+ (use your OpenClaw host's required Node version for OpenClaw).
+
+```sh
+npm install https://seller.agratys.website/integrations/ronin-buyer/ronin-buyer-0.1.0.tgz
+```
+
+The same package supports SDK, MCP, AgentKit and the thin adapters below. A registry install (`npm install ronin-buyer`) is available only after npm publication; the versioned RONIN-hosted tarball is the direct distribution path. SHA-256: [sha256.txt](https://seller.agratys.website/integrations/ronin-buyer/sha256.txt).
+
+## Buyer SDK: find / use / call
+
+```js
+import { Ronin } from 'ronin-buyer';
+import { signer } from './your-existing-wallet.js';
+
+const ronin = new Ronin({ signer, maxTotalAtomicAmount: '10000' });
+const matches = ronin.find('source verification'); // Local capability lookup, free.
+const tool = ronin.use(matches[0].tool);
+const result = await tool.call({ query: 'Find primary sources for this research question' });
+console.log(result.data, result.receipt, result.paymentResponse);
+// Equivalent: ronin.search({ task: '...' }) or ronin.call('ronin_web_research', { query: '...' }).
+```
+
+Pass your existing `@x402/core` client as `{ x402Client }` instead of `{ signer }` if payment is already configured. The package does not load, persist, request or log private keys. The optional `fetch` setting is a **plain** HTTP transport for applications/tests, not an auto-paying fetch wrapper.
+
+Input accepts `query`, `topic`, `task`, `claim`, `q`, `prompt`, `question`, `subject`, `text`, `keywords`, `search`; result-count aliases are `numResults`, `num_results`, `max_results`, `limit`, `count` (1–50). Production handles the search logic and supported metadata; the SDK validates and supplies a canonical query plus request ID. It never accepts an endpoint or payment recipient from a model.
+
+The maximum per-call payment is fixed at `10000` atomic units. `maxPaymentAtomicAmount` can lower that ceiling, never raise it. The default total budget is one call; operators may set `maxTotalAtomicAmount` for a longer session. Budget reservations and request-ID deduplication last for this client process; use your wallet's durable policy for budgets across restarts or hosts. Paid timeouts/5xx keep their reservation. Do not blindly retry an ambiguous payment with a new ID.
+
+## MCP-compatible agents
+
+Configure your buyer's existing wallet in a trusted local module exporting `createRoninOptions()`; see [examples/buyer-module.mjs](examples/buyer-module.mjs). Set the **absolute local path**, not a private key, in `RONIN_BUYER_MODULE`.
+
+```json
+{
+  "mcpServers": {
+    "ronin": {
+      "command": "npx",
+      "args": ["--yes", "--package=https://seller.agratys.website/integrations/ronin-buyer/ronin-buyer-0.1.0.tgz", "ronin-mcp"],
+      "env": { "RONIN_BUYER_MODULE": "/absolute/path/to/buyer-module.mjs" }
+    }
+  }
+}
+```
+
+Use `npx.cmd` for Windows clients that require an executable command. CLI equivalent: `ronin-mcp --buyer-module /absolute/path/to/buyer-module.mjs`. The MCP tool is `ronin_web_research`; its description explains research and source-retrieval selection. `tools/list` works without a signer; paid calls then return `BUYER_SIGNER_REQUIRED`. Transport is local stdio; the public `tools.json` is metadata, not a remote MCP endpoint. The buyer retains wallet authority.
+
+## Coinbase AgentKit
+
+```sh
+npm install @coinbase/agentkit@0.10.4
+```
+
+```js
+import { AgentKit } from '@coinbase/agentkit';
+import { roninActionProvider } from 'ronin-buyer/agentkit';
+import { walletProvider, signer } from './your-existing-wallet.js';
+
+const kit = await AgentKit.from({
+  walletProvider,
+  actionProviders: [roninActionProvider({ signer, maxTotalAtomicAmount: '10000' })],
+});
+const actions = kit.getActions(); // ronin_search and ronin_about
+// Supply these through your usual AgentKit framework binding.
+```
+
+Supports Base mainnet. The signer/x402 client comes from the buyer application; this provider does not mint a new wallet or request broad wallet permissions. No dynamic service registration is required. `ronin_about` is free.
+
+## OpenClaw
+
+```sh
+curl -fSL -o ronin-buyer-0.1.0.tgz https://seller.agratys.website/integrations/ronin-buyer/ronin-buyer-0.1.0.tgz
+openclaw plugins install npm-pack:./ronin-buyer-0.1.0.tgz
+```
+
+Configure the enabled plugin and allow its optional paid tool in your existing OpenClaw configuration:
+
+```json
+{
+  "plugins": { "entries": { "ronin-buyer": { "enabled": true, "config": { "buyerModule": "/absolute/path/to/buyer-module.mjs" } } } },
+  "tools": { "alsoAllow": ["ronin_web_research"] }
+}
+```
+
+The plugin bundles [ronin-web-research/SKILL.md](skills/ronin-web-research/SKILL.md): intent → installed tool → bounded payment → sources and receipt. Merge these fields with existing configuration. Restart/reload the gateway as required by your OpenClaw version, then inspect with `openclaw plugins inspect ronin-buyer --runtime --json`. Plugin registration is tested against the public registration contract; a full OpenClaw gateway is not installed in the build environment. Alternatively install the RONIN MCP server and use the same skill with that tool.
+
+## OpenAI and LangChain
+
+```js
+import { roninOpenAITools } from 'ronin-buyer/openai';
+const { tools, chatTools, execute } = roninOpenAITools(ronin);
+// Responses API: tools. Chat Completions: chatTools.
+// On function_call: await execute(call.name, JSON.parse(call.arguments));
+// Return JSON.stringify(result) as function_call_output with the original call_id.
+```
+
+```sh
+npm install @langchain/core@1.2.11
+```
+
+```js
+import { roninLangChainTools } from 'ronin-buyer/langchain';
+const tools = roninLangChainTools(ronin); // DynamicStructuredTool[]
+// Pass tools to your LangChain agent/tool router.
+```
+
+No LLM calls, API keys or paid model dependencies are added by these adapters.
+
+## Evidence and errors
+
+Independent local tests exercise the real MCP client/stdio transport, AgentKit `getActions`, LangChain invocation, a deterministic intent router, an unfunded ephemeral signer and a loopback mock payment gate. They cryptographically verify the authorization. A separate Python test feeds the same SDK envelope through the unmodified production `resource + roninQuote` validator and stops at a mock facilitator. These tests are **not paid sales or live model-selection evidence**.
+
+`BUYER_SIGNER_REQUIRED`, `BUYER_BUDGET_EXHAUSTED`, `PAYMENT_POLICY_REJECTED` and `RONIN_QUOTE_EXPIRED` stop before payment. `PAID_RESPONSE_UNKNOWN`, `PAID_REQUEST_FAILED` and `RECEIPT_MISSING_OR_UNCONFIRMED` retain the request ID; reconcile any `mayHavePaid` outcome before authorizing another call. HTTP receipt contents are returned as seller evidence; this SDK does not independently recognize seller revenue or perform blockchain reconciliation.
+
+## Discovery and license
+
+[x402 contract](https://seller.agratys.website/.well-known/x402), [OpenAPI](https://seller.agratys.website/openapi.json), [agents.json](https://seller.agratys.website/agents.json), [tool metadata](https://seller.agratys.website/integrations/ronin-buyer/tools.json). The production 402 also carries Bazaar metadata. `server.json` is the prepared official MCP Registry submission; it is not proof of registry publication.
+
+MIT for this package. Clean implementation using the official x402 and MCP libraries; no Agent402 code or private state is included. See NOTICE for architecture references and third-party license boundaries.

package/dist/agentkit.d.ts

@@ -0,0 +1,10 @@
+import { ActionProvider, type Action, type Network, type WalletProvider } from '@coinbase/agentkit';
+import { Ronin, type RoninOptions } from './index.js';
+/** Native AgentKit provider; the caller supplies its existing scoped payment signer/client. */
+export declare class RoninActionProvider extends ActionProvider {
+    readonly buyer: Ronin;
+    constructor(options?: RoninOptions | Ronin);
+    supportsNetwork(network: Network): boolean;
+    getActions(_walletProvider: WalletProvider): Action[];
+}
+export declare const roninActionProvider: (options?: RoninOptions | Ronin) => RoninActionProvider;

package/dist/agentkit.js

@@ -0,0 +1,23 @@
+import { ActionProvider } from '@coinbase/agentkit';
+import { z } from 'zod';
+import { Ronin, DESCRIPTION, searchSchema } from './index.js';
+/** Native AgentKit provider; the caller supplies its existing scoped payment signer/client. */
+export class RoninActionProvider extends ActionProvider {
+    buyer;
+    constructor(options = {}) {
+        super('ronin', []);
+        this.buyer = options instanceof Ronin ? options : new Ronin(options);
+    }
+    supportsNetwork(network) {
+        return network.protocolFamily === 'evm' && (network.chainId === '8453' || network.networkId === 'base-mainnet');
+    }
+    getActions(_walletProvider) {
+        return [
+            { name: 'ronin_search', description: DESCRIPTION, schema: searchSchema,
+                invoke: async (args) => JSON.stringify(await this.buyer.search(args)) },
+            { name: 'ronin_about', description: 'Get the installed RONIN search resource, exact Base USDC price and payment ceiling. Free; no network or payment.', schema: z.object({}).strict(),
+                invoke: async () => JSON.stringify(this.buyer.about()) },
+        ];
+    }
+}
+export const roninActionProvider = (options = {}) => new RoninActionProvider(options);

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { Ronin } from './index.js';
+import { loadBuyerOptions } from './config.js';
+import { serveStdio } from './mcp.js';
+const args = process.argv.slice(2);
+if (args.includes('--help')) {
+    console.log('ronin-mcp [--buyer-module /absolute/operator-owned/buyer.mjs]\nExports ronin_web_research over MCP stdio. The module exports createRoninOptions() returning an existing signer or x402Client and a bounded budget. Without it, discovery works and paid calls fail closed. No private key environment variable is supported.');
+}
+else {
+    try {
+        if (args.length && (args.length !== 2 || args[0] !== '--buyer-module'))
+            throw new Error('INVALID_ARGUMENTS');
+        const options = await loadBuyerOptions(args[1] ?? process.env.RONIN_BUYER_MODULE);
+        await serveStdio(new Ronin(options));
+    }
+    catch {
+        // Never echo imported wallet configuration, raw signer errors or key material.
+        console.error('RONIN_MCP_START_FAILED: check the trusted buyer module; use --help.');
+        process.exitCode = 1;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { RoninOptions } from './index.js';
+/** Operator-owned executable configuration; never populated from model tool arguments. */
+export declare function loadBuyerOptions(modulePath?: string): Promise<RoninOptions>;

package/dist/config.js

@@ -0,0 +1,13 @@
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Operator-owned executable configuration; never populated from model tool arguments. */
+export async function loadBuyerOptions(modulePath) {
+    if (!modulePath)
+        return {};
+    if (!isAbsolute(modulePath) || !/\.m?js$/i.test(modulePath))
+        throw new Error('BUYER_MODULE_MUST_BE_ABSOLUTE_LOCAL_JS');
+    const module = await import(pathToFileURL(modulePath).href);
+    if (typeof module.createRoninOptions !== 'function')
+        throw new Error('BUYER_MODULE_MUST_EXPORT_createRoninOptions');
+    return await module.createRoninOptions();
+}