@elizaos/plugin-hyperliquid-app 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+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

@@ -0,0 +1,95 @@
+# @elizaos/plugin-hyperliquid-app
+
+Adds native [Hyperliquid](https://hyperliquid.xyz) perpetual-market integration to elizaOS agents. Eliza agents can query market listings, credential readiness, account positions, and open orders through both conversational actions and HTTP routes. Order placement is disabled by design — the plugin is read-only.
+
+## Capabilities
+
+- **Market discovery** — list all Hyperliquid perpetual markets with max leverage, size decimals, and active/delisted status.
+- **Account positions** — read open perp positions for a configured EVM address (size, entry price, unrealized PnL, leverage, liquidation price).
+- **Open orders** — read working limit orders for a configured account.
+- **Credential status** — inspect which credential mode is active (`managed_vault`, `local_key`, or `none`) and whether account reads are available.
+- **React UI views** — standard, XR, and terminal (TUI) views shipped in the plugin bundle and surfaced as agent app tabs.
+
+## Actions
+
+### `PERPETUAL_MARKET`
+
+Conversational action that routes to the Hyperliquid provider. Recognized when the message contains Hyperliquid-related keywords (in English and several other languages) or when a `finance`, `crypto`, `trading`, or `payments` context is active.
+
+**Parameters:**
+
+| Parameter | Values | Description |
+|---|---|---|
+| `action` | `read`, `place_order` | Operation type. `place_order` returns a disabled-execution notice. |
+| `kind` | `status`, `markets`, `market`, `positions`, `funding` | Sub-kind for `action=read`. |
+| `coin` | e.g. `BTC`, `ETH` | Asset symbol for `kind=market`. |
+| `target` | `hyperliquid` (default) | Provider selector; only Hyperliquid is registered today. |
+
+**Examples:**
+- "What is the Hyperliquid trading status?" → `action=read kind=status`
+- "Show me Hyperliquid perp markets" → `action=read kind=markets`
+- "What are my Hyperliquid positions?" → `action=read kind=positions`
+- "Tell me about the BTC perp on Hyperliquid" → `action=read kind=market coin=BTC`
+
+## API routes
+
+All routes are mounted under `/api/hyperliquid/`. Public market reads require no credentials. Account reads require an EVM address to be configured.
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/hyperliquid/status` | Credential and readiness status |
+| GET | `/api/hyperliquid/markets` | All perpetual markets |
+| GET | `/api/hyperliquid/funding` | Current funding rates and asset contexts |
+| GET | `/api/hyperliquid/positions` | Account perp positions |
+| GET | `/api/hyperliquid/orders` | Open orders |
+| POST | `/api/hyperliquid/orders/open` | Disabled — returns 501 |
+| POST | `/api/hyperliquid/orders/close` | Disabled — returns 501 |
+| POST | `/api/hyperliquid/leverage` | Disabled — returns 501 |
+| POST | `/api/hyperliquid/margin` | Disabled — returns 501 |
+| POST | `/api/hyperliquid/bridge` | Disabled — returns 501 |
+| POST | `/api/hyperliquid/tpsl` | Disabled — returns 501 |
+
+## Configuration
+
+No env vars are required for public market reads. To enable account-specific reads, configure one of:
+
+| Env var | Description |
+|---|---|
+| `HYPERLIQUID_ACCOUNT_ADDRESS` or `HL_ACCOUNT_ADDRESS` | EVM address for positions/orders reads. Must be `0x`-prefixed 40-char hex. |
+| `STEWARD_EVM_ADDRESS` or `ELIZA_MANAGED_EVM_ADDRESS` | Managed-vault EVM address (takes priority over the explicit env account). |
+
+Optional signing credentials (reported in status only; this app keeps order execution disabled by design):
+
+| Env var | Description |
+|---|---|
+| `EVM_PRIVATE_KEY`, `HYPERLIQUID_PRIVATE_KEY`, or `HL_PRIVATE_KEY` | Local signer private key. |
+| `HYPERLIQUID_AGENT_KEY` or `HL_AGENT_KEY` | Hyperliquid API-wallet delegation key. |
+
+## Enabling the plugin
+
+Load `@elizaos/plugin-hyperliquid-app` in your agent character config:
+
+```json
+{
+  "plugins": ["@elizaos/plugin-hyperliquid-app"]
+}
+```
+
+Or register it programmatically:
+
+```ts
+import { hyperliquidPlugin } from "@elizaos/plugin-hyperliquid-app";
+
+const runtime = new AgentRuntime({
+  plugins: [hyperliquidPlugin],
+  // ...
+});
+```
+
+The plugin also self-registers as an elizaOS overlay app and route-plugin loader when imported, so it appears as a tab in the agent dashboard.
+
+## Notes
+
+- Order placement (POST routes) is intentionally disabled in this version. The `place_order` action op reports the blocked-execution reason rather than submitting any transaction.
+- Funding-rate reads (`kind=funding`) use Hyperliquid's live `metaAndAssetCtxs` Info API response.
+- Market data is fetched from `https://api.hyperliquid.xyz/info` (the public Hyperliquid Info API). No API key is required.

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@elizaos/plugin-hyperliquid-app",
+  "version": "2.0.11-beta.7",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "dependencies": {
+    "@elizaos/app-core": "2.0.11-beta.7",
+    "@elizaos/core": "2.0.11-beta.7",
+    "@elizaos/shared": "2.0.11-beta.7",
+    "@elizaos/ui": "2.0.11-beta.7",
+    "lucide-react": "^1.0.0",
+    "react": "^19.0.0"
+  },
+  "elizaos": {
+    "app": {
+      "heroImage": "assets/hero.png"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "clean": "rm -rf dist",
+    "test": "vitest run --config vitest.config.ts",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json"
+  },
+  "files": [
+    "assets",
+    "dist"
+  ],
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.1",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.5"
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
+}