@everestan/plugin-protocol-banks 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# elizaOS plugin
 
-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.
+A v1.x plugin: one provider (account + remaining policy in context) and two
+actions — read the account, place an order. Order arguments must arrive as
+structured `message.content` fields; this plugin deliberately does not parse
+amounts out of prose.
+
+```bash
+npm install
+npm test        # vitest: shape, refusals, fill reporting, provider
+npm run build   # tsc -> dist (ESM + d.ts)
+```
+
+Add it to a character (the package is unscoped on npm as
+`@everestan/plugin-protocol-banks` once published; until then `npm pack` it or
+run from a local path):
+
+```json
+{
+  "name": "Trader",
+  "plugins": ["@everestan/plugin-protocol-banks"],
+  "settings": { "secrets": { "PB_KEY": "pb_…" } }
+}
+```
+
+Then ask: *“What is my policy?”* or send a message whose content carries
+`{ "coin": "BTC", "side": "long", "sizeUsd": 20 }` for `PROTOCOL_BANKS_ORDER`.
+
+Why structured args: an action that guesses a notional from prose can silently
+place the wrong size. The server cap still protects the account, but the plugin
+refuses to guess.
+
+## Publish (elizaOS registry)
+
+The registry requires `images/logo.jpg` (400×400) and `images/banner.jpg`
+(1280×640) — both are committed here. Then:
+
+```bash
+npm run build
+npm publish --access public
+npx elizaos publish        # creates the plugin repo + registry PR (needs gh + npm login)
+```
+
+`npm run build` runs on `prepublishOnly`, so the tarball always carries `dist/`.
+
+**Tool-style host?** Use the hosted MCP server
+(`https://protocolbanks.com/api/mcp`, in the official MCP Registry) — it
+exposes the same account as tools.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * elizaOS plugin for the Protocol Banks Agent API (v1.x interface).
+ *
+ * The provider injects the account and the key's remaining policy into the
+ * agent's context; the actions read state and place orders. Order arguments
+ * must arrive as structured `message.content` fields (`coin`, `side`,
+ * `sizeUsd`) — this plugin deliberately does not parse amounts out of prose.
+ *
+ *   PB_KEY=pb_… elizaos dev
+ */
+import type { Plugin } from "@elizaos/core";
+export declare const protocolBanksPlugin: Plugin;
+export default protocolBanksPlugin;

package/dist/index.js

@@ -0,0 +1,87 @@
+import { ProtocolBanks } from "@everestan/protocolbanks-sdk";
+function client() {
+    const apiKey = process.env.PB_KEY;
+    if (!apiKey)
+        throw new Error("PB_KEY is not set");
+    return new ProtocolBanks({ apiKey });
+}
+const POLICY_NOTE = "The server enforces the key's policy; a 403 (policy) or 409 (guard) is final. Do not retry it unchanged.";
+const stateProvider = {
+    name: "PROTOCOL_BANKS_STATE",
+    description: "Trading account, open positions and the API key's remaining policy from Protocol Banks.",
+    dynamic: true,
+    get: async () => {
+        try {
+            const state = await client().agent.state();
+            return {
+                text: `Protocol Banks account: mode=${state.mode}, equity=$${state.account?.totalEquity ?? "?"}, positions=${state.positions?.length ?? 0}, policy=${JSON.stringify(state.policy ?? {})}. ${POLICY_NOTE}`,
+                data: {
+                    mode: state.mode,
+                    equity: state.account?.totalEquity,
+                    positions: state.positions ?? [],
+                    policy: state.policy,
+                },
+            };
+        }
+        catch (error) {
+            return { text: `Protocol Banks is not configured: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    },
+};
+const stateAction = {
+    name: "PROTOCOL_BANKS_STATE",
+    description: "Read the Protocol Banks account: mode, equity, open positions and the key's remaining policy.",
+    similes: ["TRADING_STATE", "CHECK_TRADING_AGENT"],
+    examples: [],
+    validate: async () => Boolean(process.env.PB_KEY),
+    handler: async () => {
+        const state = await client().agent.state();
+        if (state.status !== 200) {
+            return { success: false, text: `Refused (${state.status}): ${state.error ?? "no message"}` };
+        }
+        return {
+            success: true,
+            text: `mode=${state.mode} equity=$${state.account?.totalEquity} positions=${state.positions?.length ?? 0} policy=${JSON.stringify(state.policy ?? {})}`,
+        };
+    },
+};
+const orderAction = {
+    name: "PROTOCOL_BANKS_ORDER",
+    description: `Place one perpetual order through the Protocol Banks agent wallet (trading-only, cannot withdraw). ${POLICY_NOTE}`,
+    similes: ["PLACE_TRADE", "OPEN_POSITION"],
+    examples: [],
+    validate: async () => Boolean(process.env.PB_KEY),
+    handler: async (_runtime, message, _state) => {
+        // Structured fields only: the host (or the model) must supply them.
+        const content = (message.content ?? {});
+        const coin = typeof content.coin === "string" ? content.coin : "";
+        const side = content.side === "long" || content.side === "short" ? content.side : null;
+        const sizeUsd = typeof content.sizeUsd === "number" ? content.sizeUsd : Number.NaN;
+        if (!coin || !side || !Number.isFinite(sizeUsd) || sizeUsd <= 0) {
+            return {
+                success: false,
+                text: `Missing structured arguments. Provide content { coin: "BTC", side: "long"|"short", sizeUsd: number } — amounts are never parsed from prose.`,
+            };
+        }
+        const result = await client().agent.order({
+            coin,
+            side,
+            sizeUsd,
+            reason: typeof content.reason === "string" ? content.reason : undefined,
+        });
+        if (!result.ok) {
+            return { success: false, text: `Refused (${result.status}): ${result.error ?? "no message"}` };
+        }
+        return {
+            success: true,
+            text: `Filled ${result.fill?.coin} ${result.fill?.side} at $${result.fill?.avgPx} (notional $${result.fill?.notional}); remaining today $${result.remainingTodayUsd}.`,
+        };
+    },
+};
+export const protocolBanksPlugin = {
+    name: "protocol-banks",
+    description: "Execution + policy for agents: trade through a trading-only wallet with a server-enforced cap, and read the account it belongs to.",
+    providers: [stateProvider],
+    actions: [stateAction, orderAction],
+};
+export default protocolBanksPlugin;

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@everestan/plugin-protocol-banks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Trade through a trading-only Hyperliquid wallet with a server-enforced spend cap, and read the account it belongs to.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "images"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "plugin",
+    "elizaos",
+    "trading",
+    "hyperliquid",
+    "payments",
+    "spend-cap",
+    "protocol-banks"
+  ],
+  "author": "Protocol Banks",
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/everest-an/protocol-banks---web3.git",
+    "directory": "integrations/eliza"
+  },
+  "homepage": "https://protocolbanks.com/agent-api",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@elizaos/core": "^1.7.0",
+    "@everestan/protocolbanks-sdk": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.0.0",
+    "vitest": "^5.0.0"
+  }
+}