@everestan/protocolbanks-agent-tools 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @everestan/protocolbanks-agent-tools
 
-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.
+Tool definitions for the Protocol Banks Agent API — adapt once to the Vercel AI
+SDK, LangChain, OpenAI or Anthropic.
+
+```bash
+npm install @everestan/protocolbanks-sdk @everestan/protocolbanks-agent-tools
+```
+
+```ts
+import { ProtocolBanks } from "@everestan/protocolbanks-sdk"
+import { agentTools, toAnthropicTools, toOpenAIFunctions } from "@everestan/protocolbanks-agent-tools"
+
+const pb = new ProtocolBanks({ apiKey: process.env.PB_KEY! })
+const tools = agentTools(pb)
+// agent_state · place_order · prepare_payment · prepare_swap · create_invoice
+```
+
+- Parameters are plain **JSON Schema** (OpenAI and Anthropic accept them
+  directly via `toOpenAIFunctions()` / `toAnthropicTools()`; the Vercel AI SDK
+  accepts them through `jsonSchema()`; LangChain wraps them in Zod).
+- Only `place_order` executes. The other four return something the agent signs
+  itself.
+- Every tool returns the API envelope **and the HTTP status**. A `403` (key
+  policy) or `409` (guard) is returned, not thrown, and the descriptions tell
+  the model not to retry.
+
+Full adapters (AI SDK, LangChain, OpenAI, Anthropic):
+https://protocolbanks.com/docs/quickstart
+
+## License
+
+GPL-3.0-only.

package/dist/index.d.mts

@@ -0,0 +1,47 @@
+import { ProtocolBanks } from '@everestan/protocolbanks-sdk';
+
+/**
+ * Framework-agnostic tool manifest for the Protocol Banks Agent API.
+ *
+ * The server enforces the policy, so these descriptions are written for a model:
+ * say what the tool does, what the refund path is, and never suggest retrying a
+ * refusal. Each tool returns the API envelope (never throws on 403/409) so the
+ * model sees the refusal and stops.
+ *
+ * Adapt once:
+ *   - Vercel AI SDK / LangChain: wrap each definition in your framework's tool().
+ *   - OpenAI / Anthropic: pass `toOpenAIFunctions()` / `toAnthropicTools()`.
+ *   - MCP hosts: use the hosted MCP server instead (/mcp).
+ */
+
+interface AgentToolSchema {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+interface AgentToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema — accepted by OpenAI functions, Anthropic tools, AI SDK and LangChain. */
+    parameters: AgentToolSchema;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+declare function agentTools(pb: ProtocolBanks): AgentToolDefinition[];
+/** OpenAI Chat Completions / Responses function-calling format. */
+declare function toOpenAIFunctions(tools: AgentToolDefinition[]): {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: AgentToolSchema;
+    };
+}[];
+/** Anthropic Messages API tool format. */
+declare function toAnthropicTools(tools: AgentToolDefinition[]): {
+    name: string;
+    description: string;
+    input_schema: AgentToolSchema;
+}[];
+
+export { type AgentToolDefinition, type AgentToolSchema, agentTools, toAnthropicTools, toOpenAIFunctions };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { ProtocolBanks } from '@everestan/protocolbanks-sdk';
+
+/**
+ * Framework-agnostic tool manifest for the Protocol Banks Agent API.
+ *
+ * The server enforces the policy, so these descriptions are written for a model:
+ * say what the tool does, what the refund path is, and never suggest retrying a
+ * refusal. Each tool returns the API envelope (never throws on 403/409) so the
+ * model sees the refusal and stops.
+ *
+ * Adapt once:
+ *   - Vercel AI SDK / LangChain: wrap each definition in your framework's tool().
+ *   - OpenAI / Anthropic: pass `toOpenAIFunctions()` / `toAnthropicTools()`.
+ *   - MCP hosts: use the hosted MCP server instead (/mcp).
+ */
+
+interface AgentToolSchema {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+interface AgentToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema — accepted by OpenAI functions, Anthropic tools, AI SDK and LangChain. */
+    parameters: AgentToolSchema;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+declare function agentTools(pb: ProtocolBanks): AgentToolDefinition[];
+/** OpenAI Chat Completions / Responses function-calling format. */
+declare function toOpenAIFunctions(tools: AgentToolDefinition[]): {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: AgentToolSchema;
+    };
+}[];
+/** Anthropic Messages API tool format. */
+declare function toAnthropicTools(tools: AgentToolDefinition[]): {
+    name: string;
+    description: string;
+    input_schema: AgentToolSchema;
+}[];
+
+export { type AgentToolDefinition, type AgentToolSchema, agentTools, toAnthropicTools, toOpenAIFunctions };

package/dist/index.js

@@ -0,0 +1,148 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  agentTools: () => agentTools,
+  toAnthropicTools: () => toAnthropicTools,
+  toOpenAIFunctions: () => toOpenAIFunctions
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tools.ts
+var POLICY_NOTE = "The server enforces the key's policy (allowedOps, per-call cap, daily cap, coin allowlist). A 403 is a policy refusal and a 409 is a platform guard refusal; both are final for the request \u2014 do not retry unchanged.";
+function agentTools(pb) {
+  return [
+    {
+      name: "agent_state",
+      description: "Read the trading account behind the API key: mode (paper or live), equity, open positions, recent activity, and the key's policy with what it still allows today (spentTodayUsd). Call this before trading to learn the caps.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      execute: () => pb.agent.state()
+    },
+    {
+      name: "place_order",
+      description: `Open one perpetual position on Hyperliquid. This is the only tool that moves money: it executes through the account's agent wallet, which has trading-only rights and can never withdraw. ${POLICY_NOTE} A sizeUsd above the platform position cap is clamped; one above the key's per-call cap is refused.`,
+      parameters: {
+        type: "object",
+        properties: {
+          coin: { type: "string", description: 'Market symbol, e.g. "BTC". Case-insensitive.' },
+          side: { type: "string", enum: ["long", "short"] },
+          sizeUsd: { type: "number", exclusiveMinimum: 0, description: "Order notional in USD." },
+          reason: { type: "string", description: "Signal label stored with the fill (max 120 chars)." }
+        },
+        required: ["coin", "side", "sizeUsd"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.order(args)
+    },
+    {
+      name: "prepare_payment",
+      description: `Validate a payment (EVM or Solana destination, token, amount) against the key's policy and return an intent the agent signs and submits itself. The platform holds no keys and never moves the funds. ${POLICY_NOTE}`,
+      parameters: {
+        type: "object",
+        properties: {
+          to: {
+            type: "string",
+            description: "EVM address (0x + 40 hex) or base58 Solana address."
+          },
+          amountUsd: { type: "number", exclusiveMinimum: 0 },
+          token: { type: "string", description: 'Token symbol, default "USDC".' },
+          chain: { type: "string", description: 'Chain name, default "base".' },
+          memo: { type: "string", description: "Optional memo (max 140 chars)." }
+        },
+        required: ["to", "amountUsd"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.pay(args)
+    },
+    {
+      name: "prepare_swap",
+      description: `Quote a swap against the key's policy and return the route plus the transaction the agent must sign. A quote is not metered (nothing is spent) and the platform never executes it. ${POLICY_NOTE}`,
+      parameters: {
+        type: "object",
+        properties: {
+          from: {
+            type: "object",
+            description: 'Source asset, e.g. { "symbol": "USDC", "blockchain": "base" }',
+            properties: {
+              symbol: { type: "string" },
+              blockchain: { type: "string" },
+              address: { type: ["string", "null"] }
+            },
+            required: ["symbol", "blockchain"]
+          },
+          to: {
+            type: "object",
+            description: 'Destination asset, e.g. { "symbol": "ETH", "blockchain": "base" }',
+            properties: {
+              symbol: { type: "string" },
+              blockchain: { type: "string" },
+              address: { type: ["string", "null"] }
+            },
+            required: ["symbol", "blockchain"]
+          },
+          amount: { type: "string", description: "Amount in token units, as a string." },
+          amountUsd: { type: "number", exclusiveMinimum: 0, description: "USD value of the swap." },
+          slippage: { type: "number", minimum: 0.1, maximum: 5, description: "Percent; clamped to 0.1\u20135." }
+        },
+        required: ["from", "to", "amount", "amountUsd"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.swap(args)
+    },
+    {
+      name: "create_invoice",
+      description: `Create a pending invoice for work performed and return a paymentLink to hand the payer. Moves no money and is not metered; the amount is still checked against the key's policy because an invoice is a payment request. ${POLICY_NOTE}`,
+      parameters: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Payee address: EVM (0x\u2026), TRON (T\u2026) or Solana (base58)." },
+          amount: { type: "number", exclusiveMinimum: 0 },
+          token: { type: "string", description: 'Token symbol, default "USDC".' },
+          chain: { type: "string", description: "Defaults to TRON for a TRON payee, otherwise Ethereum." },
+          description: { type: "string", description: "What is being billed (max 200 chars)." },
+          expiresInHours: { type: "number", minimum: 1, maximum: 720, description: "Default 24." }
+        },
+        required: ["to", "amount"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.invoice(args)
+    }
+  ];
+}
+function toOpenAIFunctions(tools) {
+  return tools.map((tool) => ({
+    type: "function",
+    function: { name: tool.name, description: tool.description, parameters: tool.parameters }
+  }));
+}
+function toAnthropicTools(tools) {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.parameters
+  }));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  agentTools,
+  toAnthropicTools,
+  toOpenAIFunctions
+});

package/dist/index.mjs

@@ -0,0 +1,119 @@
+// src/tools.ts
+var POLICY_NOTE = "The server enforces the key's policy (allowedOps, per-call cap, daily cap, coin allowlist). A 403 is a policy refusal and a 409 is a platform guard refusal; both are final for the request \u2014 do not retry unchanged.";
+function agentTools(pb) {
+  return [
+    {
+      name: "agent_state",
+      description: "Read the trading account behind the API key: mode (paper or live), equity, open positions, recent activity, and the key's policy with what it still allows today (spentTodayUsd). Call this before trading to learn the caps.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      execute: () => pb.agent.state()
+    },
+    {
+      name: "place_order",
+      description: `Open one perpetual position on Hyperliquid. This is the only tool that moves money: it executes through the account's agent wallet, which has trading-only rights and can never withdraw. ${POLICY_NOTE} A sizeUsd above the platform position cap is clamped; one above the key's per-call cap is refused.`,
+      parameters: {
+        type: "object",
+        properties: {
+          coin: { type: "string", description: 'Market symbol, e.g. "BTC". Case-insensitive.' },
+          side: { type: "string", enum: ["long", "short"] },
+          sizeUsd: { type: "number", exclusiveMinimum: 0, description: "Order notional in USD." },
+          reason: { type: "string", description: "Signal label stored with the fill (max 120 chars)." }
+        },
+        required: ["coin", "side", "sizeUsd"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.order(args)
+    },
+    {
+      name: "prepare_payment",
+      description: `Validate a payment (EVM or Solana destination, token, amount) against the key's policy and return an intent the agent signs and submits itself. The platform holds no keys and never moves the funds. ${POLICY_NOTE}`,
+      parameters: {
+        type: "object",
+        properties: {
+          to: {
+            type: "string",
+            description: "EVM address (0x + 40 hex) or base58 Solana address."
+          },
+          amountUsd: { type: "number", exclusiveMinimum: 0 },
+          token: { type: "string", description: 'Token symbol, default "USDC".' },
+          chain: { type: "string", description: 'Chain name, default "base".' },
+          memo: { type: "string", description: "Optional memo (max 140 chars)." }
+        },
+        required: ["to", "amountUsd"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.pay(args)
+    },
+    {
+      name: "prepare_swap",
+      description: `Quote a swap against the key's policy and return the route plus the transaction the agent must sign. A quote is not metered (nothing is spent) and the platform never executes it. ${POLICY_NOTE}`,
+      parameters: {
+        type: "object",
+        properties: {
+          from: {
+            type: "object",
+            description: 'Source asset, e.g. { "symbol": "USDC", "blockchain": "base" }',
+            properties: {
+              symbol: { type: "string" },
+              blockchain: { type: "string" },
+              address: { type: ["string", "null"] }
+            },
+            required: ["symbol", "blockchain"]
+          },
+          to: {
+            type: "object",
+            description: 'Destination asset, e.g. { "symbol": "ETH", "blockchain": "base" }',
+            properties: {
+              symbol: { type: "string" },
+              blockchain: { type: "string" },
+              address: { type: ["string", "null"] }
+            },
+            required: ["symbol", "blockchain"]
+          },
+          amount: { type: "string", description: "Amount in token units, as a string." },
+          amountUsd: { type: "number", exclusiveMinimum: 0, description: "USD value of the swap." },
+          slippage: { type: "number", minimum: 0.1, maximum: 5, description: "Percent; clamped to 0.1\u20135." }
+        },
+        required: ["from", "to", "amount", "amountUsd"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.swap(args)
+    },
+    {
+      name: "create_invoice",
+      description: `Create a pending invoice for work performed and return a paymentLink to hand the payer. Moves no money and is not metered; the amount is still checked against the key's policy because an invoice is a payment request. ${POLICY_NOTE}`,
+      parameters: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Payee address: EVM (0x\u2026), TRON (T\u2026) or Solana (base58)." },
+          amount: { type: "number", exclusiveMinimum: 0 },
+          token: { type: "string", description: 'Token symbol, default "USDC".' },
+          chain: { type: "string", description: "Defaults to TRON for a TRON payee, otherwise Ethereum." },
+          description: { type: "string", description: "What is being billed (max 200 chars)." },
+          expiresInHours: { type: "number", minimum: 1, maximum: 720, description: "Default 24." }
+        },
+        required: ["to", "amount"],
+        additionalProperties: false
+      },
+      execute: (args) => pb.agent.invoice(args)
+    }
+  ];
+}
+function toOpenAIFunctions(tools) {
+  return tools.map((tool) => ({
+    type: "function",
+    function: { name: tool.name, description: tool.description, parameters: tool.parameters }
+  }));
+}
+function toAnthropicTools(tools) {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.parameters
+  }));
+}
+export {
+  agentTools,
+  toAnthropicTools,
+  toOpenAIFunctions
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@everestan/protocolbanks-agent-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Tool definitions for the Protocol Banks Agent API — adapt once to the Vercel AI SDK, LangChain, OpenAI or Anthropic",
+  "homepage": "https://protocolbanks.com/agent-api",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai-agents",
+    "tools",
+    "function-calling",
+    "langchain",
+    "vercel-ai-sdk",
+    "openai",
+    "anthropic",
+    "trading",
+    "hyperliquid",
+    "protocol-banks"
+  ],
+  "author": "Protocol Banks",
+  "license": "GPL-3.0-only",
+  "peerDependencies": {
+    "@everestan/protocolbanks-sdk": ">=0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "@types/node": "^22"
+  }
+}