@xyz17711/token-verdict 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @xyz17711/token-verdict
 
-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.
+[![Publish](https://github.com/17711-services/clients/actions/workflows/publish-node.yml/badge.svg)](https://github.com/17711-services/clients/actions/workflows/publish-node.yml)
+[![npm](https://img.shields.io/npm/v/@xyz17711/token-verdict)](https://www.npmjs.com/package/@xyz17711/token-verdict)
+[![License](https://img.shields.io/npm/l/@xyz17711/token-verdict)](https://github.com/17711-services/clients/blob/main/LICENSE)
+
+Typed TypeScript client for **🪙 token-verdict-service**, part of the
+[17711.xyz](https://api.17711.xyz) microservice fleet -- pay-per-call APIs settled in USDC via
+[x402](https://x402.org), listed on [x402scan](https://www.x402scan.com/server/f1c7b972-3405-4b75-8b4f-d1bfbd6305ff).
+
+## Install
+
+```bash
+npm install @xyz17711/token-verdict
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `getVerdict` | Token verdict and security check: is this token safe? Honeypot, rug pull and scam detection with taxes, liquidity and admin powers ($0.01, x402) |
+
+## Quickstart
+
+```typescript
+import { Client } from "@xyz17711/token-verdict";
+
+const client = new Client("https://api.17711.xyz/registry/🪙 token-verdict-service");
+// see the Methods table above for every available call and its request/response type
+```
+
+## Paying past the free quota
+
+Every gated tool allows a small number of free calls per day; beyond that it returns a 402
+challenge. Without a wallet configured, this client throws `PaymentRequiredError` with the price,
+network, and payee address attached:
+
+```typescript
+import { Client, PaymentRequiredError } from "@xyz17711/token-verdict";
+
+const client = new Client("https://api.17711.xyz/registry/🪙 token-verdict-service");
+try {
+  await client.getVerdict(/* ... */);
+} catch (e) {
+  if (e instanceof PaymentRequiredError) {
+    console.log(`needs ${e.priceUsdc} USDC on ${e.network}, payable to ${e.payTo}`);
+  }
+}
+```
+
+To pay automatically, configure a wallet on the client -- the private key should come from your
+own environment/secrets manager, never a literal string in source code:
+
+```typescript
+import { Client } from "@xyz17711/token-verdict";
+
+const client = new Client("https://api.17711.xyz/registry/🪙 token-verdict-service", {
+  x402PrivateKey: process.env.X402_PRIVATE_KEY,
+  x402ExpectedNetwork: "eip155:8453", // Base mainnet; use eip155:84532 for Base Sepolia testnet
+  x402MaxPaymentUsdc: 0.01,           // refuse any single call above this
+  x402MaxTotalSpendUsdc: 1.0,         // refuse once this WALLET's lifetime spend would exceed it
+});
+```
+
+**Never commit a private key.** Both spend caps are required together with the key -- a wallet
+with real funds and no explicit caps refuses to construct at all (`WalletConfigError`), on
+purpose. The cumulative cap is tracked per wallet address, shared by every `Client` you construct
+with that same key in this process.
+
+## LangChain.js
+
+```typescript
+import { Client } from "@xyz17711/token-verdict";
+import { TokenVerdictToolkit } from "@xyz17711/token-verdict/langchain";
+
+const client = new Client("https://api.17711.xyz/registry/🪙 token-verdict-service", { /* ...wallet options... */ });
+const tools = new TokenVerdictToolkit(client).getTools();
+```
+
+Requires the optional `@langchain/core`+`zod` peer dependencies (`npm install @langchain/core
+zod`) -- importing the base package above never requires them; only `@xyz17711/token-verdict/langchain`
+does.
+
+## License
+
+MIT -- see [`LICENSE`](../../LICENSE), shared by every language's client library in the
+`clients` repo this package lives in.

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Typed HTTP client and request/response interfaces for 🪙 token-verdict-service.
+ */
+import { Client as BaseClient, type ClientOptions } from "@xyz17711/core";
+export interface ContractInfo {
+    /** Whether the contract can block addresses. */
+    blacklist?: boolean | null;
+    /** Whether the real owner is hidden. */
+    hidden_owner?: boolean | null;
+    /** Whether new tokens can be minted. */
+    mintable?: boolean | null;
+    /** Owner address, absent when ownership is renounced. */
+    owner?: string | null;
+    /** Whether a previous owner can take ownership back. */
+    owner_can_reclaim?: boolean | null;
+    ownership_renounced: boolean;
+    /** Whether transfers can be paused. */
+    pausable?: boolean | null;
+    /** Whether it is an upgradeable proxy (the logic can be replaced). */
+    proxy?: boolean | null;
+    /** Whether the contract can self-destruct. */
+    self_destruct?: boolean | null;
+    /** Whether the source code is published and verified. */
+    source_verified?: boolean | null;
+    /** Whether the owner can change the taxes after launch. */
+    taxes_modifiable?: boolean | null;
+}
+export interface Finding {
+    /** Stable code, e.g. `trading.honeypot`, `liquidity.low`, `contract.mintable`. */
+    code: string;
+    message: string;
+    /** `critical`, `high`, `medium`, `low` or `info`. */
+    severity: string;
+}
+export interface HoldersInfo {
+    count?: number | null;
+    /** Share of the supply held by the creator, in percent. */
+    creator_percent?: number | null;
+    /** Share of the supply held by the owner, in percent. */
+    owner_percent?: number | null;
+    /** Share held by the ten largest wallets that are not contracts, in percent. */
+    top10_wallets_percent?: number | null;
+}
+export interface LiquidityInfo {
+    /** Share of the liquidity-token supply that is locked, in percent. */
+    locked_percent?: number | null;
+    /** Age in days of the oldest trading pool. */
+    pool_age_days?: number | null;
+    pools: number;
+    /** Largest pool: exchange name. */
+    top_pool?: string | null;
+    /** Liquidity in USD summed over the trading pools. */
+    total_usd: number;
+}
+export interface MarketInfo {
+    buys_24h: number;
+    fully_diluted_value_usd?: number | null;
+    price_change_24h_percent?: number | null;
+    price_usd?: number | null;
+    sells_24h: number;
+    volume_24h_usd: number;
+}
+export interface TradingInfo {
+    /** Buy tax in percent. */
+    buy_tax_percent?: number | null;
+    /** Whether a holder cannot sell their whole balance. */
+    cannot_sell_all?: boolean | null;
+    /** Whether the token cannot be sold after being bought. */
+    honeypot?: boolean | null;
+    /** Sell tax in percent. */
+    sell_tax_percent?: number | null;
+}
+export interface GetVerdictResponse {
+    address: string;
+    /** How old this verdict is, in seconds (0 for a fresh check). */
+    age_seconds: number;
+    chain: string;
+    contract: ContractInfo;
+    /** Always states that this is an automated risk screen, not advice. */
+    disclaimer: string;
+    /** Everything that drove the verdict, most severe first. */
+    findings: Finding[];
+    /** `true` when served from a stored result. */
+    from_cache: boolean;
+    holders: HoldersInfo;
+    liquidity: LiquidityInfo;
+    market: MarketInfo;
+    name?: string | null;
+    /** When the data was read (UTC). */
+    retrieved_at: string;
+    /** 0 to 100, higher is safer; derived from the findings. */
+    safety_score: number;
+    /** The data sources consulted. */
+    sources: string[];
+    symbol?: string | null;
+    trading: TradingInfo;
+    /** `safe`, `caution`, `danger` or `unknown` (the security source did not answer: not a green light). */
+    verdict: string;
+}
+export interface GetVerdictRequest {
+    /** The token contract address (`0x` followed by 40 hex characters). */
+    address: string;
+    /** The chain: `base` (default), `ethereum`, `bsc`, `polygon`, `arbitrum`, `optimism` or `avalanche`. */
+    chain?: string | null;
+    /** The oldest verdict you accept, in seconds. Omit it for the default (verdicts up to 5 minutes old); `0` forces a fresh check. The response always says how old it is. */
+    max_age_seconds?: number | null;
+}
+/** Typed client for 🪙 token-verdict-service, e.g. `client.getVerdict(...)`. */
+export declare class Client extends BaseClient {
+    /** Token verdict and security check: is this token safe? Honeypot, rug pull and scam detection with taxes, liquidity and admin powers ($0.01, x402) */
+    getVerdict(request: GetVerdictRequest): Promise<GetVerdictResponse>;
+}
+export { ClientOptions };

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Typed HTTP client and request/response interfaces for 🪙 token-verdict-service.
+ */
+import { Client as BaseClient } from "@xyz17711/core";
+/** Typed client for 🪙 token-verdict-service, e.g. `client.getVerdict(...)`. */
+export class Client extends BaseClient {
+    /** Token verdict and security check: is this token safe? Honeypot, rug pull and scam detection with taxes, liquidity and admin powers ($0.01, x402) */
+    async getVerdict(request) {
+        return this.post("/v1/token-verdict/get_verdict", request);
+    }
+}

package/dist/langchain.d.ts

@@ -0,0 +1,22 @@
+/**
+ * LangChain.js tools for 🪙 token-verdict-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `token-verdict/langchain`, never from the package root, so importing the base client never requires them installed.
+ */
+import { z } from "zod";
+import { Client } from "./index.js";
+export declare class TokenVerdictToolkit {
+    private client;
+    constructor(client: Client);
+    getTools(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        address: z.ZodString;
+        chain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        max_age_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>, {
+        address: string;
+        chain?: string | null | undefined;
+        max_age_seconds?: number | null | undefined;
+    }, {
+        address: string;
+        chain?: string | null | undefined;
+        max_age_seconds?: number | null | undefined;
+    }, import("./index.js").GetVerdictResponse, unknown, "getVerdict">[];
+}

package/dist/langchain.js

@@ -0,0 +1,19 @@
+/**
+ * LangChain.js tools for 🪙 token-verdict-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `token-verdict/langchain`, never from the package root, so importing the base client never requires them installed.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+export class TokenVerdictToolkit {
+    constructor(client) {
+        this.client = client;
+    }
+    getTools() {
+        return [
+            tool(async (input) => this.client.getVerdict(input), {
+                name: "getVerdict",
+                description: "Token verdict and security check: is this token safe? Honeypot, rug pull and scam detection with taxes, liquidity and admin powers ($0.01, x402)",
+                schema: z.object({ address: z.string(), chain: z.string().nullable().optional(), max_age_seconds: z.number().nullable().optional() }),
+            }),
+        ];
+    }
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@xyz17711/token-verdict",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Generated typed client for the 🪙 token-verdict-service 17711.xyz microservice.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "default": "./dist/langchain.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@xyz17711/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3",
+    "zod": "^3 || ^4"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "@langchain/core": "^1.2",
+    "zod": "^4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+/**
+ * Typed HTTP client and request/response interfaces for 🪙 token-verdict-service.
+ */
+
+import { Client as BaseClient, type ClientOptions } from "@xyz17711/core";
+
+export interface ContractInfo {
+  /** Whether the contract can block addresses. */
+  blacklist?: boolean | null;
+  /** Whether the real owner is hidden. */
+  hidden_owner?: boolean | null;
+  /** Whether new tokens can be minted. */
+  mintable?: boolean | null;
+  /** Owner address, absent when ownership is renounced. */
+  owner?: string | null;
+  /** Whether a previous owner can take ownership back. */
+  owner_can_reclaim?: boolean | null;
+  ownership_renounced: boolean;
+  /** Whether transfers can be paused. */
+  pausable?: boolean | null;
+  /** Whether it is an upgradeable proxy (the logic can be replaced). */
+  proxy?: boolean | null;
+  /** Whether the contract can self-destruct. */
+  self_destruct?: boolean | null;
+  /** Whether the source code is published and verified. */
+  source_verified?: boolean | null;
+  /** Whether the owner can change the taxes after launch. */
+  taxes_modifiable?: boolean | null;
+}
+
+export interface Finding {
+  /** Stable code, e.g. `trading.honeypot`, `liquidity.low`, `contract.mintable`. */
+  code: string;
+  message: string;
+  /** `critical`, `high`, `medium`, `low` or `info`. */
+  severity: string;
+}
+
+export interface HoldersInfo {
+  count?: number | null;
+  /** Share of the supply held by the creator, in percent. */
+  creator_percent?: number | null;
+  /** Share of the supply held by the owner, in percent. */
+  owner_percent?: number | null;
+  /** Share held by the ten largest wallets that are not contracts, in percent. */
+  top10_wallets_percent?: number | null;
+}
+
+export interface LiquidityInfo {
+  /** Share of the liquidity-token supply that is locked, in percent. */
+  locked_percent?: number | null;
+  /** Age in days of the oldest trading pool. */
+  pool_age_days?: number | null;
+  pools: number;
+  /** Largest pool: exchange name. */
+  top_pool?: string | null;
+  /** Liquidity in USD summed over the trading pools. */
+  total_usd: number;
+}
+
+export interface MarketInfo {
+  buys_24h: number;
+  fully_diluted_value_usd?: number | null;
+  price_change_24h_percent?: number | null;
+  price_usd?: number | null;
+  sells_24h: number;
+  volume_24h_usd: number;
+}
+
+export interface TradingInfo {
+  /** Buy tax in percent. */
+  buy_tax_percent?: number | null;
+  /** Whether a holder cannot sell their whole balance. */
+  cannot_sell_all?: boolean | null;
+  /** Whether the token cannot be sold after being bought. */
+  honeypot?: boolean | null;
+  /** Sell tax in percent. */
+  sell_tax_percent?: number | null;
+}
+
+export interface GetVerdictResponse {
+  address: string;
+  /** How old this verdict is, in seconds (0 for a fresh check). */
+  age_seconds: number;
+  chain: string;
+  contract: ContractInfo;
+  /** Always states that this is an automated risk screen, not advice. */
+  disclaimer: string;
+  /** Everything that drove the verdict, most severe first. */
+  findings: Finding[];
+  /** `true` when served from a stored result. */
+  from_cache: boolean;
+  holders: HoldersInfo;
+  liquidity: LiquidityInfo;
+  market: MarketInfo;
+  name?: string | null;
+  /** When the data was read (UTC). */
+  retrieved_at: string;
+  /** 0 to 100, higher is safer; derived from the findings. */
+  safety_score: number;
+  /** The data sources consulted. */
+  sources: string[];
+  symbol?: string | null;
+  trading: TradingInfo;
+  /** `safe`, `caution`, `danger` or `unknown` (the security source did not answer: not a green light). */
+  verdict: string;
+}
+
+export interface GetVerdictRequest {
+  /** The token contract address (`0x` followed by 40 hex characters). */
+  address: string;
+  /** The chain: `base` (default), `ethereum`, `bsc`, `polygon`, `arbitrum`, `optimism` or `avalanche`. */
+  chain?: string | null;
+  /** The oldest verdict you accept, in seconds. Omit it for the default (verdicts up to 5 minutes old); `0` forces a fresh check. The response always says how old it is. */
+  max_age_seconds?: number | null;
+}
+
+/** Typed client for 🪙 token-verdict-service, e.g. `client.getVerdict(...)`. */
+export class Client extends BaseClient {
+  /** Token verdict and security check: is this token safe? Honeypot, rug pull and scam detection with taxes, liquidity and admin powers ($0.01, x402) */
+  async getVerdict(request: GetVerdictRequest): Promise<GetVerdictResponse> {
+    return this.post<GetVerdictResponse>("/v1/token-verdict/get_verdict", request);
+  }
+}
+
+export { ClientOptions };

package/src/langchain.ts

@@ -0,0 +1,28 @@
+/**
+ * LangChain.js tools for 🪙 token-verdict-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `token-verdict/langchain`, never from the package root, so importing the base client never requires them installed.
+ */
+
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { Client } from "./index.js";
+
+export class TokenVerdictToolkit {
+  private client: Client;
+
+  constructor(client: Client) {
+    this.client = client;
+  }
+
+  getTools() {
+    return [
+      tool(
+        async (input) => this.client.getVerdict(input),
+        {
+          name: "getVerdict",
+          description: "Token verdict and security check: is this token safe? Honeypot, rug pull and scam detection with taxes, liquidity and admin powers ($0.01, x402)",
+          schema: z.object({ address: z.string(), chain: z.string().nullable().optional(), max_age_seconds: z.number().nullable().optional() }),
+        },
+      ),
+    ];
+  }
+}

package/test/index.test.mjs

@@ -0,0 +1,24 @@
+/**
+ * Verifies every token-verdict client method sends a request to the expected path/HTTP verb and parses a well-formed response -- one test per operation, real fetch mocked via a plain reassignment of `globalThis.fetch` (no extra test/mocking dependency). Runs against the COMPILED package (`../dist/index.js`) -- build before testing.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Client } from "../dist/index.js";
+
+test("getVerdict calls the expected path", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url, init = {}) => {
+    const parsed = new URL(url);
+    assert.equal((init.method ?? "GET").toUpperCase(), "POST");
+    assert.equal(parsed.pathname, "/v1/token-verdict/get_verdict");
+    return new Response(JSON.stringify({ address: "test", age_seconds: 0, chain: "test", contract: { blacklist: null, hidden_owner: null, mintable: null, owner: null, owner_can_reclaim: null, ownership_renounced: false, pausable: null, proxy: null, self_destruct: null, source_verified: null, taxes_modifiable: null }, disclaimer: "test", findings: [], from_cache: false, holders: { count: null, creator_percent: null, owner_percent: null, top10_wallets_percent: null }, liquidity: { locked_percent: null, pool_age_days: null, pools: 0, top_pool: null, total_usd: 0 }, market: { buys_24h: 0, fully_diluted_value_usd: null, price_change_24h_percent: null, price_usd: null, sells_24h: 0, volume_24h_usd: 0 }, name: null, retrieved_at: "test", safety_score: 0, sources: [], symbol: null, trading: { buy_tax_percent: null, cannot_sell_all: null, honeypot: null, sell_tax_percent: null }, verdict: "test" }), { status: 200 });
+  };
+  try {
+    const client = new Client("https://example.test");
+    const result = await client.getVerdict({ address: "test", chain: null, max_age_seconds: null });
+    assert.ok(result !== undefined);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

package/test/langchain.test.mjs

@@ -0,0 +1,16 @@
+/**
+ * Verifies every token-verdict LangChain tool through the real StructuredTool (`.invoke()`), not just the underlying client method -- catches schema-shape bugs a plain client-method test would miss. Requires the `langchain`/`zod` dev dependencies.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Client } from "../dist/index.js";
+import { TokenVerdictToolkit } from "../dist/langchain.js";
+
+test("getVerdict tool invoke", async () => {
+  globalThis.fetch = async () => new Response(JSON.stringify({ address: "test", age_seconds: 0, chain: "test", contract: { blacklist: null, hidden_owner: null, mintable: null, owner: null, owner_can_reclaim: null, ownership_renounced: false, pausable: null, proxy: null, self_destruct: null, source_verified: null, taxes_modifiable: null }, disclaimer: "test", findings: [], from_cache: false, holders: { count: null, creator_percent: null, owner_percent: null, top10_wallets_percent: null }, liquidity: { locked_percent: null, pool_age_days: null, pools: 0, top_pool: null, total_usd: 0 }, market: { buys_24h: 0, fully_diluted_value_usd: null, price_change_24h_percent: null, price_usd: null, sells_24h: 0, volume_24h_usd: 0 }, name: null, retrieved_at: "test", safety_score: 0, sources: [], symbol: null, trading: { buy_tax_percent: null, cannot_sell_all: null, honeypot: null, sell_tax_percent: null }, verdict: "test" }), { status: 200 });
+  const toolkit = new TokenVerdictToolkit(new Client("https://example.test"));
+  const t = toolkit.getTools().find((x) => x.name === "getVerdict");
+  const result = await t.invoke({ address: "test", chain: "test", max_age_seconds: 0 });
+  assert.ok(result !== undefined);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src"
+  ]
+}