@blackhull/agentkit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @blackhull/agentkit
 
-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.
+[![ci](https://github.com/blackhull-systems/agentkit/actions/workflows/ci.yml/badge.svg)](https://github.com/blackhull-systems/agentkit/actions/workflows/ci.yml) [![security](https://github.com/blackhull-systems/agentkit/actions/workflows/security.yml/badge.svg)](https://github.com/blackhull-systems/agentkit/actions/workflows/security.yml)
+
+A [Coinbase AgentKit](https://github.com/coinbase/agentkit) action provider for **Blackhull**: checks your agent runs
+*before* it pays or trades, sold per call over [x402](https://x402.org). Every answer is a measurement of public data
+with its evidence. Facts, not financial advice.
+
+| Action | What it answers | Price |
+|---|---|---|
+| `check_token` | A Base token's owner, mint / pause / blacklist / fee powers in its code (proxies resolved), upgradeability and its pools' liquidity on Uniswap v2, v3 and v4, Aerodrome and Slipstream, with finding codes such as `CAN_MINT`, `UPGRADEABLE`, `THIN_LIQUIDITY` | $0.01 |
+| `check_x402_service` | A paid x402 service's grade and finding codes (`detailed: true` for the full report with evidence) | $0.003 / $0.008 |
+| `find_provider` | The best-rated paid providers for a job within a budget, ranked neutrally | $0.003 |
+
+## Install
+
+```bash
+npm install @blackhull/agentkit
+```
+
+```ts
+import { AgentKit } from "@coinbase/agentkit";
+import { blackhullActionProvider } from "@blackhull/agentkit";
+
+const agentkit = await AgentKit.from({
+  walletProvider,                                   // any EVM wallet provider on base-mainnet
+  actionProviders: [blackhullActionProvider()],     // add it next to your other providers
+});
+```
+
+Your agent's own wallet pays, in USDC on Base. It needs a little USDC (a dollar covers 100 token checks).
+
+## Safety
+
+- **Price cap:** every price quote is read before anything is signed, and a quote above `maxPriceUsdc` (default
+  `0.05`), or one whose price cannot be read, is refused. The cap applies to whichever client signs, including one you
+  bring; the client the provider builds from your wallet also has the x402 library's own spend cap. An invalid cap
+  (`NaN`, `Infinity`, zero or negative) is refused when the provider is created. To tighten it:
+  `blackhullActionProvider({ maxPriceUsdc: 0.02 })`.
+- **No charge for no answer:** if Blackhull cannot answer (for example the chain cannot be read), it declines before the
+  payment settles.
+- **Try it free:** `blackhullActionProvider({ trialMode: true })` answers each action's fixed sample query at no charge.
+
+## Payment receipts and custom signers
+
+A paid answer includes the settlement `receipt` (transaction hash, network, payer), so your agent can keep proof of
+every check it bought. To pay through a custodial or policy-controlled signer instead of the agent's wallet, pass your
+own client: `blackhullActionProvider({ x402Client })`.
+
+## Verification
+
+`npm test` runs the provider's safety behaviour offline (trial mode, the price cap with the wallet's client and with
+your own, unreadable quotes, invalid caps, no charge for no answer, receipts), with nothing paid or sent, and fails
+below its coverage thresholds. CI also runs Prettier, ESLint, the TypeScript compiler and the package checks (publint,
+are-the-types-wrong) on Node 22 and 24, from the committed lockfile. Every release is also verified with a **real paid
+call** through this provider's code, paid by Blackhull's own test wallet to Blackhull. [VERIFICATION.md](VERIFICATION.md) records that run
+and its on-chain transaction.
+
+Built and maintained by Blackhull's AI system; every release is reviewed and signed by its owner.
+
+## Docs
+
+Products, prices, codes and errors: <https://blackhullsystems.com/docs> · Terms: <https://blackhull.systems/terms>
+
+Made by [Black Hull Systems LLC](https://blackhull.systems), veteran-owned, Charleston, South Carolina. Support:
+support@blackhull.systems

package/dist/blackhullActionProvider.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Blackhull Action Provider for Coinbase AgentKit.
+ *
+ * Checks an agent should run BEFORE it pays or trades, sold per call over x402 by Blackhull (https://blackhull.systems):
+ *   - check_token          a Base token's owner, mint/pause/blacklist/fee powers, upgradeability and liquidity ($0.01)
+ *   - check_x402_service   grade and finding codes (or the full findings report) for a paid x402 service ($0.003-$0.008)
+ *   - find_provider        the best-rated paid providers for a job within a budget ($0.003)
+ * Every answer is a measurement of public data with its evidence. Facts, not financial advice.
+ *
+ * The agent's own wallet pays (or a client you bring). Every price quote is read before anything is signed, and any
+ * quote above maxPriceUsdc, or one that cannot be read, is refused.
+ */
+import { z } from "zod";
+import { ActionProvider, EvmWalletProvider, Network } from "@coinbase/agentkit";
+import { x402Client } from "@x402/fetch";
+import type { ClientEvmSigner } from "@x402/evm";
+export interface BlackhullConfig {
+    /** Most the provider will ever pay for one call, in USDC: a finite number of at least 0.000001 (default 0.05). */
+    maxPriceUsdc?: number;
+    /** Free trial: answer each action's fixed sample query (?sample=1) instead of paying. */
+    trialMode?: boolean;
+    /** Override the API origin (tests). */
+    baseUrl?: string;
+    /** Bring your own x402 payment client (e.g. a custodial or policy-controlled signer). Default: one built from the
+     *  agent's wallet provider, as AgentKit's own x402 provider builds it. The price cap applies to either. */
+    x402Client?: x402Client;
+}
+export declare const CheckTokenSchema: z.ZodObject<{
+    address: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    address: string;
+}, {
+    address: string;
+}>;
+export declare const CheckServiceSchema: z.ZodObject<{
+    url: z.ZodString;
+    detailed: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    detailed?: boolean | undefined;
+}, {
+    url: string;
+    detailed?: boolean | undefined;
+}>;
+export declare const FindProviderSchema: z.ZodObject<{
+    capability: z.ZodString;
+    maxPriceUsdc: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    capability: string;
+    maxPriceUsdc?: number | undefined;
+}, {
+    capability: string;
+    maxPriceUsdc?: number | undefined;
+}>;
+export declare class BlackhullActionProvider extends ActionProvider<EvmWalletProvider> {
+    private readonly base;
+    private readonly maxAtomic;
+    private readonly trial;
+    private readonly client?;
+    constructor(config?: BlackhullConfig);
+    checkToken(walletProvider: EvmWalletProvider, args: z.infer<typeof CheckTokenSchema>): Promise<string>;
+    checkService(walletProvider: EvmWalletProvider, args: z.infer<typeof CheckServiceSchema>): Promise<string>;
+    findProvider(walletProvider: EvmWalletProvider, args: z.infer<typeof FindProviderSchema>): Promise<string>;
+    supportsNetwork: (network: Network) => boolean;
+    /** One check: quote, refuse above the cap, pay, return the answer (or a JSON error, never a throw). */
+    call(walletProvider: EvmWalletProvider, path: string, query: Record<string, string>): Promise<string>;
+    private walletClient;
+    private answer;
+}
+/**
+ * The most an x402 v2 quote (its PAYMENT-REQUIRED header) can charge, in atomic USDC, taken over every payment option
+ * it offers, since the signing client picks the option. null when there is no header, it does not parse, or any option
+ * is not an integer amount of USDC on Base: a quote that cannot be read is never paid.
+ */
+export declare function quotedAtomic(quote: Response): number | null;
+/** The x402 signer for an AgentKit wallet: the wallet's own account, reading the chain through the wallet provider. */
+export declare function walletSigner(walletProvider: EvmWalletProvider): ClientEvmSigner;
+export declare const blackhullActionProvider: (config?: BlackhullConfig) => BlackhullActionProvider;

package/dist/blackhullActionProvider.js

@@ -0,0 +1,237 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blackhullActionProvider = exports.BlackhullActionProvider = exports.FindProviderSchema = exports.CheckServiceSchema = exports.CheckTokenSchema = void 0;
+exports.quotedAtomic = quotedAtomic;
+exports.walletSigner = walletSigner;
+/**
+ * Blackhull Action Provider for Coinbase AgentKit.
+ *
+ * Checks an agent should run BEFORE it pays or trades, sold per call over x402 by Blackhull (https://blackhull.systems):
+ *   - check_token          a Base token's owner, mint/pause/blacklist/fee powers, upgradeability and liquidity ($0.01)
+ *   - check_x402_service   grade and finding codes (or the full findings report) for a paid x402 service ($0.003-$0.008)
+ *   - find_provider        the best-rated paid providers for a job within a budget ($0.003)
+ * Every answer is a measurement of public data with its evidence. Facts, not financial advice.
+ *
+ * The agent's own wallet pays (or a client you bring). Every price quote is read before anything is signed, and any
+ * quote above maxPriceUsdc, or one that cannot be read, is refused.
+ */
+const zod_1 = require("zod");
+const agentkit_1 = require("@coinbase/agentkit");
+const fetch_1 = require("@x402/fetch");
+const client_1 = require("@x402/evm/exact/client");
+const version_1 = require("./version");
+const UA = `blackhull-agentkit/${version_1.VERSION}`;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/** The only asset and network Blackhull is paid in: USDC on Base. */
+const USDC_BASE = { network: "eip155:8453", asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" };
+exports.CheckTokenSchema = zod_1.z
+    .object({ address: zod_1.z.string().regex(ADDRESS).describe("The token contract address on Base (0x + 40 hex)") })
+    .strip();
+exports.CheckServiceSchema = zod_1.z
+    .object({
+    url: zod_1.z.string().url().describe("The x402 resource URL of the paid service to check"),
+    detailed: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Full findings report with evidence ($0.008) instead of grade and codes ($0.003)"),
+})
+    .strip();
+exports.FindProviderSchema = zod_1.z
+    .object({
+    capability: zod_1.z.string().min(1).describe("A category, e.g. search, ai-analysis, llm-inference, web-data, onchain"),
+    maxPriceUsdc: zod_1.z
+        .number()
+        .positive()
+        .optional()
+        .describe("The most your agent will pay that provider per call, USDC"),
+})
+    .strip();
+/** Atomic USDC (6 decimals) as a plain decimal string, e.g. 10000 -> "0.01". */
+const usdc = (atomic) => (atomic / 1e6).toString();
+/** Thrown inside the payment path when a quote is refused, so nothing is signed; reported as a JSON error. */
+class NotPaid extends Error {
+}
+class BlackhullActionProvider extends agentkit_1.ActionProvider {
+    base;
+    maxAtomic;
+    trial;
+    client;
+    constructor(config = {}) {
+        super("blackhull", []);
+        const max = config.maxPriceUsdc ?? 0.05;
+        // floor, so the cap is never above what was asked; NaN, Infinity or a cap that rounds to 0 is a setup error
+        const atomic = Math.floor(max * 1e6);
+        if (typeof max !== "number" || !Number.isFinite(max) || atomic < 1) {
+            throw new RangeError(`maxPriceUsdc must be a finite number of at least 0.000001 USDC, got ${String(max)}`);
+        }
+        this.base = new URL(config.baseUrl ?? "https://blackhullsystems.com").href.replace(/\/+$/, "");
+        this.maxAtomic = atomic;
+        this.trial = Boolean(config.trialMode);
+        this.client = config.x402Client;
+    }
+    async checkToken(walletProvider, args) {
+        return this.call(walletProvider, "/check/token", { address: args.address });
+    }
+    async checkService(walletProvider, args) {
+        return this.call(walletProvider, args.detailed ? "/verdict/x402" : "/flags", { url: args.url });
+    }
+    async findProvider(walletProvider, args) {
+        const q = { capability: args.capability };
+        if (args.maxPriceUsdc !== undefined)
+            q.max_price = String(args.maxPriceUsdc);
+        return this.call(walletProvider, "/route", q);
+    }
+    supportsNetwork = (network) => network.networkId === "base-mainnet";
+    /** One check: quote, refuse above the cap, pay, return the answer (or a JSON error, never a throw). */
+    async call(walletProvider, path, query) {
+        const url = new URL(this.base + path);
+        const headers = { "user-agent": UA };
+        try {
+            if (this.trial) {
+                url.searchParams.set("sample", "1");
+                return await this.answer(await fetch(url, { headers }), { trial: true });
+            }
+            for (const [k, v] of Object.entries(query))
+                url.searchParams.set(k, v);
+            let paidAtomic;
+            // The payment wrapper asks for the quote through this fetch and signs only what it returns, so the cap is
+            // checked on the very quote that gets signed, whichever x402 client signs it.
+            const guarded = async (input, init) => {
+                const res = await fetch(input, init);
+                if (res.status === 402) {
+                    const amount = quotedAtomic(res);
+                    if (amount === null)
+                        throw new NotPaid("price unreadable or not in USDC on Base; not paid");
+                    if (amount > this.maxAtomic) {
+                        throw new NotPaid(`price ${usdc(amount)} USDC is above maxPriceUsdc ${usdc(this.maxAtomic)}; not paid`);
+                    }
+                    paidAtomic = amount;
+                }
+                return res;
+            };
+            const pay = (0, fetch_1.wrapFetchWithPayment)(guarded, this.client ?? this.walletClient(walletProvider));
+            const res = await pay(url.toString(), { headers });
+            // 404 and other non-402 answers are never charged
+            return await this.answer(res, paidAtomic !== undefined && res.ok ? { price_usdc: paidAtomic / 1e6 } : {});
+        }
+        catch (e) {
+            return JSON.stringify({ error: true, message: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    walletClient(walletProvider) {
+        // a second, independent cap: the x402 library refuses to sign above it too
+        const client = new fetch_1.x402Client().setSpendControls({ maxAmountPerPayment: `$${usdc(this.maxAtomic)}` });
+        (0, client_1.registerExactEvmScheme)(client, { signer: walletSigner(walletProvider) });
+        return client;
+    }
+    async answer(res, extra) {
+        const text = await res.text();
+        let body = text;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // not JSON: keep the text
+        }
+        if (!res.ok)
+            return JSON.stringify({ error: true, status: res.status, ...extra, body });
+        // the settlement receipt (transaction hash, network, payer), when a payment was made
+        const r = res.headers.get("payment-response") ?? res.headers.get("x-payment-response");
+        let receipt;
+        try {
+            receipt = r ? JSON.parse(Buffer.from(r, "base64").toString("utf8")) : undefined;
+        }
+        catch {
+            receipt = undefined;
+        }
+        return JSON.stringify({ ...extra, ...(receipt ? { receipt } : {}), result: body });
+    }
+}
+exports.BlackhullActionProvider = BlackhullActionProvider;
+__decorate([
+    (0, agentkit_1.CreateAction)({
+        name: "check_token",
+        description: `Check a token on Base before trading it. Returns measured facts read live from the chain, each with its evidence:
+who controls the contract (owner), whether its code can mint, pause, blacklist or change fees, whether it is an upgradeable
+proxy, and how much WETH, ETH or USDC its pools hold on Uniswap v2, v3 and v4, Aerodrome and Slipstream, plus finding
+codes such as OWNER_ACTIVE, CAN_MINT, UPGRADEABLE, THIN_LIQUIDITY or NO_POOL_FOUND. Costs $0.01 USDC per call via x402 (paid from this wallet). Facts, not financial advice.`,
+        schema: exports.CheckTokenSchema,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [agentkit_1.EvmWalletProvider, void 0]),
+    __metadata("design:returntype", Promise)
+], BlackhullActionProvider.prototype, "checkToken", null);
+__decorate([
+    (0, agentkit_1.CreateAction)({
+        name: "check_x402_service",
+        description: `Check a paid x402 service before your agent pays it: Blackhull's grade (CLEAN / CAUTION / WARNING /
+INSUFFICIENT_DATA) and coded findings measured from on-chain payments — e.g. whether it is actually paid at its listed
+price, by how many independent buyers, whether its demand is concentrated or self-funded. $0.003 for grade and codes,
+$0.008 for the full report with evidence (detailed: true). Facts, not advice.`,
+        schema: exports.CheckServiceSchema,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [agentkit_1.EvmWalletProvider, void 0]),
+    __metadata("design:returntype", Promise)
+], BlackhullActionProvider.prototype, "checkService", null);
+__decorate([
+    (0, agentkit_1.CreateAction)({
+        name: "find_provider",
+        description: `Find the best-rated paid x402 providers for a job within a budget, ranked neutrally by grade, then
+chain-verified buyers, then price (WARNING-graded providers excluded). $0.003 per call via x402.`,
+        schema: exports.FindProviderSchema,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [agentkit_1.EvmWalletProvider, void 0]),
+    __metadata("design:returntype", Promise)
+], BlackhullActionProvider.prototype, "findProvider", null);
+/**
+ * The most an x402 v2 quote (its PAYMENT-REQUIRED header) can charge, in atomic USDC, taken over every payment option
+ * it offers, since the signing client picks the option. null when there is no header, it does not parse, or any option
+ * is not an integer amount of USDC on Base: a quote that cannot be read is never paid.
+ */
+function quotedAtomic(quote) {
+    const h = quote.headers.get("payment-required");
+    if (!h)
+        return null;
+    let accepts;
+    try {
+        accepts = JSON.parse(Buffer.from(h, "base64").toString("utf8")).accepts;
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(accepts) || accepts.length === 0)
+        return null;
+    let most = 0;
+    for (const a of accepts) {
+        const usdc = a.network === USDC_BASE.network && String(a.asset).toLowerCase() === USDC_BASE.asset;
+        if (!usdc || typeof a.amount !== "string" || !/^\d{1,15}$/.test(a.amount))
+            return null;
+        most = Math.max(most, Number(a.amount));
+    }
+    return most;
+}
+/** The x402 signer for an AgentKit wallet: the wallet's own account, reading the chain through the wallet provider. */
+function walletSigner(walletProvider) {
+    return {
+        ...walletProvider.toSigner(),
+        readContract: (a) => walletProvider.readContract({
+            address: a.address,
+            abi: a.abi,
+            functionName: a.functionName,
+            args: a.args,
+        }),
+    };
+}
+const blackhullActionProvider = (config) => new BlackhullActionProvider(config);
+exports.blackhullActionProvider = blackhullActionProvider;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { BlackhullActionProvider, blackhullActionProvider, type BlackhullConfig } from "./blackhullActionProvider";

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blackhullActionProvider = exports.BlackhullActionProvider = void 0;
+var blackhullActionProvider_1 = require("./blackhullActionProvider");
+Object.defineProperty(exports, "BlackhullActionProvider", { enumerable: true, get: function () { return blackhullActionProvider_1.BlackhullActionProvider; } });
+Object.defineProperty(exports, "blackhullActionProvider", { enumerable: true, get: function () { return blackhullActionProvider_1.blackhullActionProvider; } });

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version, sent in the user-agent; a test keeps it equal to package.json's. */
+export declare const VERSION = "0.1.1";

package/dist/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** This package's version, sent in the user-agent; a test keeps it equal to package.json's. */
+exports.VERSION = "0.1.1";

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@blackhull/agentkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Coinbase AgentKit action provider for Blackhull: check a Base token, an x402 service or find the best provider before your agent pays or trades. Paid per call over x402; facts with evidence, not advice.",
+  "license": "Apache-2.0",
+  "author": "Black Hull Systems LLC <support@blackhull.systems>",
+  "homepage": "https://blackhullsystems.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blackhull-systems/agentkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blackhull-systems/agentkit/issues",
+    "email": "support@blackhull.systems"
+  },
+  "keywords": [
+    "agentkit",
+    "x402",
+    "base",
+    "ai-agents",
+    "token-risk",
+    "action-provider",
+    "blackhull"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --max-warnings 0 .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "npm run build && node --test --experimental-test-coverage --test-coverage-include=dist/** --test-coverage-lines=95 --test-coverage-branches=90 --test-coverage-functions=95 test/*.test.cjs",
+    "check:package": "npm run build && publint --strict && attw --pack . --profile node16",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run check:package",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@coinbase/agentkit": "^0.10.0"
+  },
+  "dependencies": {
+    "@x402/evm": "^2.29.0",
+    "@x402/fetch": "^2.29.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@coinbase/agentkit": "^0.10.4",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "eslint": "^10.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.14.0",
+    "prettier": "^3.9.10",
+    "publint": "^0.3.25",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "viem": "^2.57.16"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}