@goassay-ai/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Assay
+
+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/README.md

@@ -1,3 +1,253 @@
-# Temporary Holding Version
+# @goassay-ai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Node SDK for [Assay](https://goassay.ai): call tools over MCP, with free calls and paid calls signed by a key you hold.
+
+**Status: early release (0.x).** The API can still change before 1.0; see the [changelog](https://github.com/assay-ai/assay-sdk/blob/main/node/CHANGELOG.md).
+
+```sh
+npm install @goassay-ai/sdk
+```
+
+Requires Node 22 or newer. ESM only. Documentation: [docs.goassay.ai/developers](https://docs.goassay.ai/developers).
+
+The client reads your API key from the `apiKey` option or the `ASSAY_API_KEY` environment variable. What the key may do is set on the key, as scopes: `tools:call` for calls, `payments` for paid calls and binding a key, `activity:read` for receipts.
+
+## Free call
+
+```ts
+import { Assay } from "@goassay-ai/sdk";
+
+const assay = new Assay(); // ASSAY_API_KEY
+
+const found = await assay.tools.search("weather forecast", { limit: 5 });
+const tool = await assay.tools.get("weather_forecast"); // schemas, price
+const res = await assay.tools.call("weather_forecast", { city: "Lisbon" });
+
+res.structuredContent; // the tool's output
+res.isError; // true only for the provider's own tool error
+res.receipt; // what the call cost
+```
+
+## Choose a URL
+
+A client calls tools through one MCP URL. `mcpUrl` takes a full URL or a path on `https://mcp.goassay.ai`; the path is checked against the shapes Assay serves when the client is built, so a typo is a `ConfigError` at once. `assay.at(urlOrPath)` returns a client for another URL that shares this one's API key, signers, spend limits and ledger, `onPayment`, `fetch` and logger, and keeps its own quote cache.
+
+```ts
+import { Assay } from "@goassay-ai/sdk";
+
+const everything = new Assay(); // "/": the whole catalogue, found with tools.search
+const research = new Assay({ mcpUrl: "/my/research" }); // your tool set (Draft; "/my/research@2" for version 2)
+const weather = new Assay({ mcpUrl: "/?tools=get_weather" }); // a single tool
+
+// Two URLs in one program: one key, one set of limits.
+const kit = everything.at("/@acme/twitter-kit@3"); // a public tool set, version 3
+const { tools } = await kit.tools.list(); // tools/list: the set's tools, with prices
+await kit.tools.call("acme__get_profile", { user: "x" }); // a provider tool: {handle}__{tool}, sent unchanged
+await everything.tools.call("get_weather", { city: "Lisbon" });
+```
+
+| Path                                         | Serves                                                                                        |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `/`                                          | Everything (default)                                                                          |
+| `/my/{slug}`, `/my/{slug}@{n}`               | your tool set: the Draft, or version `n`                                                      |
+| `/@{handle}/{slug}`, `/@{handle}/{slug}@{n}` | a public tool set                                                                             |
+| `/u/{token}`, `/u/{token}@{n}`               | a link-only tool set; the token is a secret, shown as `/u/…` in `toString`, `toJSON` and logs |
+| `/c/{category}`, `/@{handle}`                | one topic, one maker                                                                          |
+
+Filters on any path: `?tools=a,b` (one name gives a single-tool URL; `name@1` pins a contract major), `?category=x`, `?free=1`, `?discovery=auto|full|search`. A URL the server does not serve to your key throws `McpUrlNotFoundError`.
+
+Paid calls go through whatever URL you choose: the SDK keeps no per-URL paid list. To keep a client free-only, use a key without the `payments` scope, add `?free=1` to its URL, or refuse in `onPayment`. A tool set grant that allows its tools only through its own URL needs that URL; on `/` those tools are `TOOL_NOT_ALLOWED`.
+
+## Paid call with a local key
+
+The SDK never stores or creates keys. You pass a signer; for a local key, wrap a viem account:
+
+```sh
+npm install viem
+```
+
+```ts
+import { Assay, evmSigner } from "@goassay-ai/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const assay = new Assay({
+  signer: evmSigner(privateKeyToAccount(process.env.PAYMENT_KEY as `0x${string}`)),
+  limits: { maxPerCall: "0.50", maxPerDay: "5" }, // dollars; see "Spend limits"
+  onPayment: (p) => BigInt(p.amount.amount) <= 100_000n, // your own rule; false refuses
+});
+
+const res = await assay.tools.call("weather_forecast", { city: "Lisbon" });
+```
+
+`evmSigner()` returns a frozen object. To wrap signing (for logging or counting), build a new signer object around it instead of changing it in place:
+
+```ts
+import type { TypedData } from "@goassay-ai/sdk";
+
+const base = evmSigner(account);
+const signer = {
+  namespace: base.namespace,
+  address: base.address,
+  signTypedData: async (typedData: TypedData) => {
+    console.log("signing", typedData.primaryType);
+    return base.signTypedData(typedData);
+  },
+};
+```
+
+On a paid tool the server answers `PAYMENT_REQUIRED`. The SDK then checks the requirement with its local guards (G1 to G12, including the chain reads of your key's grant), calls `onPayment`, signs one voucher, and sends the same call again with the same idempotency key. Network retries resend the same request; a voucher is never signed twice for one logical call, even when you start the same call twice at once.
+
+### Retrying safely
+
+Every call has an idempotency key: yours (`{ idempotencyKey }`) or one the SDK creates. Every error out of `tools.call` carries it as `err.idempotencyKey`. Calling again with that key is safe: Assay replays a call it already served and does not charge twice.
+
+```ts
+try {
+  return await assay.tools.call("weather_forecast", { city: "Lisbon" });
+} catch (e) {
+  if (e instanceof AssayError && e.retryable && e.idempotencyKey) {
+    return await assay.tools.call("weather_forecast", { city: "Lisbon" }, { idempotencyKey: e.idempotencyKey });
+  }
+  throw e;
+}
+```
+
+For work you may redo after a restart, pass your own key (for example `order-${orderId}-weather`).
+
+### Spend limits
+
+With a signer, every voucher is checked against local limits before it is signed:
+
+- **Defaults: $0.50 per call and $5 per rolling 24 hours**, per signing key.
+- Change them with `limits: { maxPerCall, maxPerDay }` (dollars, as strings).
+- The record is in memory, per process: a restart starts again at zero, and worker threads or several processes each have their own. The on-chain caps that the payer set when approving the key bound it across processes.
+
+`onPayment(details)` sees each payment (tool, network, amount, provider, payer, idempotency key) after every check passed and before it is signed. Use it for your own rules, for example an allow-list of providers:
+
+```ts
+const allowed = new Set(["eip155:<chainId>:<provider address>"]);
+const assay = new Assay({ signer, onPayment: (p) => allowed.has(p.provider) });
+```
+
+Answer quickly: the voucher's lifetime (at most 240 s) starts before the hook runs.
+
+### Networks
+
+Payments are checked against a network table the client holds (escrow, asset, decimals and RPC URLs per network), never against what the server says, so a compromised API cannot redirect a payment.
+
+- The SDK ships a built-in table, pinned in the release; an address change ships as a new SDK release. It holds Robinhood Chain testnet (`eip155:46630`), the network Assay's production runs on today: the USDG escrow `0x2723…Ce18`, 6 decimals, and two public RPCs from different operators. A paid call or a bind on a network that is in no table is refused with `PaymentNetworkUnknownError`, which names the network.
+- `networks` configures any chain yourself: a test chain, or another deployment together with its own `mcpUrl`, `apiUrl` and `webUrl`. Your entries are merged over the built-in table. A new network is added; an entry for a built-in network replaces it whole, so fields are never mixed from two deployments.
+- `rpcUrls: { "eip155:<chainId>": ["https://your-rpc"] }` replaces only a network's RPC URLs, for example with your private RPC.
+
+Addresses must be checksummed CAIP-10 / CAIP-19 ids on the network's chain. RPC URLs must be https (plain http only to localhost).
+
+```ts
+const assay = new Assay({
+  mcpUrl: "https://mcp.your-deployment.example/",
+  apiUrl: "https://api.your-deployment.example/api/v1",
+  webUrl: "https://portal.your-deployment.example",
+  signer,
+  networks: {
+    "eip155:<chainId>": {
+      // chainId: optional; when given it must be the id in the key
+      escrow: "eip155:<chainId>:<escrow contract address>",
+      asset: "eip155:<chainId>/erc20:<token address>",
+      decimals: 6,
+      rpcUrls: ["https://<rpc 1>", "https://<rpc 2>"],
+    },
+  },
+});
+```
+
+### Binding the key (once)
+
+Before its first paid call, the key is bound to your API key and a person approves it:
+
+```ts
+const status = await assay.paidCalls.status();
+if (status.state !== "active") {
+  const setup = await assay.paidCalls.bind(); // challenge, field check, sign, bind
+  console.log(`Approve at ${setup.approvalUrl}; the page must show ${setup.fingerprint}`);
+  await assay.paidCalls.waitUntilActive({ timeoutMs: 15 * 60_000 });
+}
+```
+
+If another key is already bound to the API key, `bind()` answers `bindStatus: "PENDING_APPROVAL"`: the old key stays `delegate` and keeps signing, this key is `pendingDelegate`, and it replaces the old one only when the person approves it. `waitUntilActive()` resolves once `delegate` is this client's key and its paid calls are on. A key that is bound to another API key is refused with `DelegateAlreadyBoundError` (409). If another key wins a first bind at the same moment, `bind()` raises `DelegateBindConflictError` (409, `retryable`): nothing was bound, and calling `bind()` once more parks this key as `pendingDelegate` (`bindStatus: "PENDING_APPROVAL"`) for the person to approve.
+
+The approval link is built on the web app's origin (`webUrl`, default `https://portal.goassay.ai`). A link the server sends is used only when it is on that same origin. The key's address travels only in the URL fragment. The approval cannot be automated: a person opens the link and compares the fingerprint.
+
+## Reading a receipt
+
+Only a paid call has a receipt to fetch. A free call's `res.receipt.intentId` is `null`: it has no intent, and `res.receipt` already says it cost nothing.
+
+```ts
+const intentId = res.receipt?.intentId;
+if (intentId) {
+  const receipt = await assay.receipts.get(intentId);
+  receipt.chargedPrice; // { amount: "100000", asset: "eip155:...", decimals: 6 }
+}
+```
+
+## Handling errors
+
+Every error is an `AssayError` with a stable `code`. Branch on the class or the code, never on the message. A missing scope is a `ScopeMissingError` naming `requiredScope`, on the MCP host and on the API alike; a key without `payments` that calls a paid tool gets a `ScopeMissingError` naming `payments`, and nothing is signed or sent again; a route only a signed-in person may use is a `HumanSessionRequiredError` (an `AuthError`).
+
+```ts
+import {
+  AssayError,
+  HumanSessionRequiredError,
+  PaymentNetworkUnknownError,
+  PaymentRefusedError,
+  McpUrlNotFoundError,
+  PaymentRequiredError,
+  RateLimitError,
+  ScopeMissingError,
+} from "@goassay-ai/sdk";
+
+try {
+  await assay.tools.call("weather_forecast", { city: "Lisbon" });
+} catch (e) {
+  if (e instanceof ScopeMissingError) console.error(`the API key needs the ${e.requiredScope} scope`);
+  else if (e instanceof HumanSessionRequiredError) console.error("only a signed-in person can do this");
+  else if (e instanceof McpUrlNotFoundError) console.error("this MCP URL is not served to this key");
+  else if (e instanceof PaymentRequiredError) console.error("paid tool: pass a signer");
+  else if (e instanceof PaymentNetworkUnknownError) console.error(`network ${e.network} is not supported yet`);
+  else if (e instanceof PaymentRefusedError) console.error(`refused before signing by ${e.guard}: ${e.code}`);
+  else if (e instanceof RateLimitError) console.error(`retry in ${e.retryAfterMs} ms`);
+  else if (e instanceof AssayError) console.error(e.code, e.message);
+  else throw e;
+}
+```
+
+## Options
+
+| Option               | Default                                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| `apiKey`             | `ASSAY_API_KEY`                                                                                  |
+| `mcpUrl`, `apiUrl`   | `https://mcp.goassay.ai/` (a URL or a path; see "Choose a URL"), `https://api.goassay.ai/api/v1` |
+| `signer` / `signers` | none (free calls only)                                                                           |
+| `networks`           | none (needed for paid calls)                                                                     |
+| `limits`             | `{ maxPerCall: "0.50", maxPerDay: "5" }`                                                         |
+| `onPayment`          | none                                                                                             |
+| `fetch`              | the global `fetch`                                                                               |
+| `timeoutMs`          | 120 000 per attempt                                                                              |
+| `maxRetries`         | 2, with backoff, honouring `Retry-After`                                                         |
+| `logger`             | silent; never logs keys, headers, bodies or signatures                                           |
+| `now`, `sleep`       | the system clock (corrected by the server's `Date` for vouchers), `setTimeout`                   |
+
+The protocol core (EIP-712 voucher and binding, guards, clock) is at `@goassay-ai/sdk/core`.
+
+## Development
+
+```sh
+npm ci
+npm run lint
+npm run typecheck
+npm test
+```
+
+The tests run the shared vectors in [`vectors/`](https://github.com/assay-ai/assay-sdk/tree/main/vectors) (`vectors/eip155/`) and unit tests on a fake transport.
+
+## License
+
+MIT, see [LICENSE](https://github.com/assay-ai/assay-sdk/blob/main/node/LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,88 @@
+import { inspect } from "node:util";
+import { type FetchLike, type Logger } from "./http.js";
+import { PaidCalls } from "./resources/paid-calls.js";
+import { type OnPayment } from "./resources/context.js";
+import { Receipts } from "./resources/receipts.js";
+import { Tools } from "./resources/tools.js";
+import { type Eip155Network, type Limits } from "./schemes/eip155/index.js";
+import type { NetworkEntry } from "./schemes/eip155/index.js";
+import { type Signer } from "./signer.js";
+export declare const DEFAULT_MCP_URL = "https://mcp.goassay.ai/";
+export declare const DEFAULT_API_URL = "https://api.goassay.ai/api/v1";
+/** The web app, where a person approves a payment key. */
+export declare const DEFAULT_WEB_URL = "https://portal.goassay.ai";
+export interface AssayOptions {
+    /** Your Assay API key. Default: the `ASSAY_API_KEY` environment variable. */
+    apiKey?: string;
+    /**
+     * The MCP URL this client calls tools through: a full URL, or a path resolved against
+     * `https://mcp.goassay.ai`, such as `"/my/research"`, `"/@acme/kit@3"` or `"/?tools=get_weather"`.
+     * Checked against the URL shapes Assay serves. Default `https://mcp.goassay.ai/` (Everything).
+     * Paid calls go through whatever URL you choose; use `at()` for another URL in the same program.
+     */
+    mcpUrl?: string;
+    /** The REST API base. Default `https://api.goassay.ai/api/v1`. */
+    apiUrl?: string;
+    /** A signer for paid calls. Free calls need none. */
+    signer?: Signer;
+    /** Several signers; a payment uses the one whose namespace matches the requirement's network. */
+    signers?: Signer[];
+    /** The web app, for the payment-key approval link. Default `https://portal.goassay.ai`. */
+    webUrl?: string;
+    /**
+     * Payment networks you configure, keyed by CAIP-2 (`eip155:<chainId>`): chainId, escrow, asset,
+     * decimals and RPC URLs, for example a test chain or another deployment (with its own `mcpUrl`,
+     * `apiUrl` and `webUrl`). Merged over the SDK's built-in table: a new network is added, and an
+     * entry for a built-in network replaces it whole. Never read from the server.
+     */
+    networks?: Record<string, Eip155Network>;
+    /** Your own RPC URLs for a network, replacing the table's public ones: `{"eip155:<id>": [url]}`. */
+    rpcUrls?: Record<string, string[]>;
+    /**
+     * Local spend limits in dollars, checked before every signature (G7), per signing key and per
+     * process. Default `{maxPerCall: "0.50", maxPerDay: "5"}` (rolling 24 hours).
+     */
+    limits?: Limits;
+    /** Called before each voucher is signed, after every local check passed. Return `false` to refuse. */
+    onPayment?: OnPayment;
+    /** Default: the global `fetch`. */
+    fetch?: FetchLike;
+    /** Per attempt, in milliseconds. Default 120 000. */
+    timeoutMs?: number;
+    /** Retries of a failed request (network errors, 408/429/5xx, rate limits). Default 2. */
+    maxRetries?: number;
+    /** Default: silent. Lines never carry keys or signatures. */
+    logger?: Logger;
+    /** Milliseconds clock. Default `Date.now`; corrected by the server's `Date` for vouchers. */
+    now?: () => number;
+    /** How the client waits between retries. Default `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The Assay client, for one MCP URL. Stateless over HTTP: there is nothing to connect or close.
+ *
+ * - `tools.list / search / get / call` over MCP;
+ * - `receipts.get` to see what a call cost;
+ * - `paidCalls.status / bind / waitUntilActive` to set up a payment key;
+ * - `at(url)` for a client on another MCP URL that shares this one's key, signers and limits.
+ */
+export declare class Assay {
+    #private;
+    readonly tools: Tools;
+    readonly receipts: Receipts;
+    readonly paidCalls: PaidCalls;
+    /** The payment network table in use: the built-in one with `networks` merged, after `rpcUrls`. */
+    readonly networks: ReadonlyMap<string, NetworkEntry>;
+    constructor(options?: AssayOptions);
+    /**
+     * A client on another MCP URL: a full URL on this client's MCP origin, or a path resolved
+     * against it (`"/my/research"`, `"/@acme/kit@3"`, `"/?tools=get_weather"`). It shares this
+     * client's API key, HTTP stack (fetch, retries, logger), signers, spend limits and ledger,
+     * `onPayment` and the in-flight calls by idempotency key, and has its own quote cache. Cheap:
+     * nothing is sent until it is used.
+     */
+    at(urlOrPath: string): Assay;
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+    [inspect.custom](): string;
+}

package/dist/client.js

@@ -0,0 +1,158 @@
+import { inspect } from "node:util";
+import { ChainReader } from "./core/chain.js";
+import { ConfigError } from "./errors.js";
+import { Http, silentLogger } from "./http.js";
+import { McpTransport } from "./mcp.js";
+import { DEFAULT_MCP_ORIGIN, redactMcpUrl, resolveMcpUrl } from "./mcp-url.js";
+import { networkTable } from "./networks.js";
+import { PaidCalls } from "./resources/paid-calls.js";
+import { QuoteCache } from "./resources/context.js";
+import { Receipts } from "./resources/receipts.js";
+import { Tools } from "./resources/tools.js";
+import { RestClient } from "./rest.js";
+import { checkLimits, DEFAULT_LIMITS, Eip155Scheme } from "./schemes/eip155/index.js";
+import { signerNamespace } from "./signer.js";
+import { VERSION } from "./version.js";
+export const DEFAULT_MCP_URL = "https://mcp.goassay.ai/";
+export const DEFAULT_API_URL = "https://api.goassay.ai/api/v1";
+/** The web app, where a person approves a payment key. */
+export const DEFAULT_WEB_URL = "https://portal.goassay.ai";
+function originOf(name, value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ConfigError(`${name} is not a URL`);
+    }
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if (!(url.protocol === "https:" || (url.protocol === "http:" && loopback)) || url.username || url.password) {
+        throw new ConfigError(`${name} must be an https URL`);
+    }
+    return url.origin;
+}
+const CLIENT_INFO = { name: "goassay-node", version: VERSION };
+/** Builds a sibling client from a parent's context (`at()`); not reachable through the public options. */
+const SIBLING = Symbol("assay.sibling");
+/**
+ * The Assay client, for one MCP URL. Stateless over HTTP: there is nothing to connect or close.
+ *
+ * - `tools.list / search / get / call` over MCP;
+ * - `receipts.get` to see what a call cost;
+ * - `paidCalls.status / bind / waitUntilActive` to set up a payment key;
+ * - `at(url)` for a client on another MCP URL that shares this one's key, signers and limits.
+ */
+export class Assay {
+    tools;
+    receipts;
+    paidCalls;
+    /** The payment network table in use: the built-in one with `networks` merged, after `rpcUrls`. */
+    networks;
+    #ctx;
+    #mcpOrigin;
+    constructor(options = {}) {
+        const sibling = options[SIBLING];
+        const ctx = sibling ?? buildContext(options);
+        this.#ctx = ctx;
+        this.#mcpOrigin = new URL(ctx.mcpUrl).origin;
+        this.tools = new Tools(ctx);
+        this.receipts = new Receipts(ctx);
+        this.paidCalls = new PaidCalls(ctx);
+        this.networks = ctx.networks;
+    }
+    /**
+     * A client on another MCP URL: a full URL on this client's MCP origin, or a path resolved
+     * against it (`"/my/research"`, `"/@acme/kit@3"`, `"/?tools=get_weather"`). It shares this
+     * client's API key, HTTP stack (fetch, retries, logger), signers, spend limits and ledger,
+     * `onPayment` and the in-flight calls by idempotency key, and has its own quote cache. Cheap:
+     * nothing is sent until it is used.
+     */
+    at(urlOrPath) {
+        const mcpUrl = resolveMcpUrl("url", urlOrPath, this.#mcpOrigin);
+        if (new URL(mcpUrl).origin !== this.#mcpOrigin)
+            throw new ConfigError("at() takes a path or a URL on this client's MCP origin; build a new Assay for another");
+        const c = this.#ctx;
+        const ctx = {
+            ...c,
+            mcpUrl,
+            mcp: new McpTransport(c.http, mcpUrl, CLIENT_INFO, c.now),
+            quotes: new QuoteCache(c.now),
+        };
+        return new Assay({ [SIBLING]: ctx });
+    }
+    toJSON() {
+        return { mcpUrl: redactMcpUrl(this.#ctx.mcpUrl) };
+    }
+    toString() {
+        return `Assay(${redactMcpUrl(this.#ctx.mcpUrl)})`;
+    }
+    [inspect.custom]() {
+        return this.toString();
+    }
+}
+function buildContext(options) {
+    const apiKey = (options.apiKey ?? process.env.ASSAY_API_KEY ?? "").trim();
+    if (apiKey === "")
+        throw new ConfigError("an API key is required: pass apiKey or set ASSAY_API_KEY");
+    if (!/^[\x21-\x7e]+$/.test(apiKey))
+        throw new ConfigError("apiKey is not valid");
+    const mcpUrl = resolveMcpUrl("mcpUrl", options.mcpUrl ?? DEFAULT_MCP_URL, DEFAULT_MCP_ORIGIN);
+    const apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, "");
+    const origins = [originOf("mcpUrl", mcpUrl), originOf("apiUrl", apiUrl)];
+    const webOrigin = originOf("webUrl", options.webUrl ?? DEFAULT_WEB_URL);
+    const signers = [...(options.signer ? [options.signer] : []), ...(options.signers ?? [])];
+    for (const s of signers) {
+        if (signerNamespace(s) === null)
+            throw new ConfigError("a signer needs namespace, address and signTypedData");
+    }
+    if (new Set(signers.map((s) => s.namespace)).size !== signers.length)
+        throw new ConfigError("give one signer per namespace");
+    const maxRetries = options.maxRetries ?? 2;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 10)
+        throw new ConfigError("maxRetries must be 0 to 10");
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new ConfigError("timeoutMs must be positive");
+    const now = options.now ?? Date.now;
+    const fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const http = new Http({
+        fetch: fetchFn,
+        apiKey,
+        origins,
+        timeoutMs,
+        maxRetries,
+        logger: options.logger ?? silentLogger,
+        now,
+        sleep,
+        userAgent: `goassay-node/${VERSION} node/${process.versions.node}`,
+    });
+    const networks = networkTable(options.networks, options.rpcUrls);
+    const schemes = new Map();
+    if (signers.some((s) => s.namespace === "eip155")) {
+        schemes.set("eip155", new Eip155Scheme({
+            networks,
+            limits: checkLimits(options.limits ?? DEFAULT_LIMITS),
+            // Chain reads go to the caller's RPCs, without the API key.
+            chain: new ChainReader({ fetch: fetchFn, now }),
+            now,
+            dateOffset: () => http.dateOffset,
+        }));
+    }
+    return {
+        http,
+        mcpUrl,
+        mcp: new McpTransport(http, mcpUrl, CLIENT_INFO, now),
+        api: new RestClient(http, apiUrl, now),
+        signers: Object.freeze(signers),
+        schemes,
+        networks,
+        webOrigin,
+        inFlight: new Map(),
+        quotes: new QuoteCache(now),
+        onPayment: options.onPayment,
+        maxRetries,
+        now,
+        sleep,
+    };
+}

package/dist/core/binding.d.ts

@@ -0,0 +1,56 @@
+import { type Address } from "./hex.js";
+/** The binding proof's own EIP-712 domain (spec section 5). Not the escrow's. */
+export declare const DELEGATE_BINDING_DOMAIN_NAME = "GoAssay Agent Binding";
+export declare const DELEGATE_BINDING_DOMAIN_VERSION = "1";
+/** The longest challenge life a client accepts: the server's challenge TTL. */
+export declare const MAX_BINDING_CHALLENGE_SECONDS = 300;
+/** Exactly these fields, in this order. The order is part of the type hash. */
+export declare const DELEGATE_BINDING_TYPES: {
+    readonly DelegateBinding: readonly [{
+        readonly name: "delegate";
+        readonly type: "address";
+    }, {
+        readonly name: "credentialId";
+        readonly type: "string";
+    }, {
+        readonly name: "nonce";
+        readonly type: "string";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint64";
+    }];
+};
+/** What a client signs: rebuilt from its own constants after every challenge field was checked. */
+export interface DelegateBindingTypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+    types: typeof DELEGATE_BINDING_TYPES;
+    primaryType: "DelegateBinding";
+    message: {
+        delegate: Address;
+        credentialId: string;
+        nonce: string;
+        expiresAt: bigint;
+    };
+}
+/** The typed data for checked values. */
+export declare function bindingTypedData(chainId: number, message: DelegateBindingTypedData["message"]): DelegateBindingTypedData;
+export interface BindingContext {
+    /** The client's own payment key address. */
+    localAddress: string;
+    /** The credential id of the API key. */
+    credentialId: string;
+    /** The chain id of the network the client is configured for, from its own table. */
+    chainId: number;
+    /** The corrected clock, Unix seconds (spec section 7). */
+    nowSeconds: number;
+}
+/**
+ * Checks the server's `DelegateBinding` challenge (the `data` of the challenge answer) field by
+ * field (spec section 5.2) and returns the typed data to sign, rebuilt from the client's own
+ * constants. Throws `SignerRefusal` naming the first field that fails.
+ */
+export declare function checkBindingChallenge(challenge: unknown, ctx: BindingContext): DelegateBindingTypedData;