Vincent - HyperLiquid for agents

Use this skill to create a HyperLiquid perpetuals and spot wallet for your agent. Trade perps, check spot balances, and transfer USDC between perps and spot sub-accounts. The generated EOA is the HyperLiquid account — fund it directly via the HL bridge and start trading immediately with no Safe deployment or collateral approval steps.

The agent never sees the private key. All operations are executed server-side. The agent receives a scoped API key that can only perform actions permitted by the wallet owner's policies.

All commands use the @vincentai/cli package. API keys are stored and resolved automatically.

Security Model

No environment variables are required. The agent creates its own HyperLiquid wallet at runtime by calling the Vincent API, which returns a scoped API key. There is no pre-existing credential to configure.

The generated EOA is a standalone HyperLiquid account. Unlike Polymarket (which deploys a Gnosis Safe), the EOA private key IS the HyperLiquid account. Deposits go directly to this address via the HyperLiquid bridge from Arbitrum, or via usdSend from another HL account.

The agent's API key is not a private key. It is a scoped Bearer token enforced server-side. The Vincent server evaluates all policies before executing any trade. If a trade violates a policy, the server rejects it. If a trade requires human approval, the server holds it and notifies the wallet owner via Telegram.

All API calls go exclusively to heyvincent.ai over HTTPS/TLS. The service calls api.hyperliquid.xyz server-side on the agent's behalf.

Key lifecycle:

• - Creation: Agent runs secret create — Vincent generates the EOA, stores the key, returns keyId, walletAddress, and claimUrl.
• Claim: Human operator uses the claim URL to take ownership and configure policies at https://heyvincent.ai.
• Revocation: Wallet owner revokes the agent's API key from the frontend at any time.
• Re-linking: Agent exchanges a one-time re-link token (generated by the owner) for a new key via secret relink.

Quick Start

1. Check for Existing Keys

Before creating a new wallet, check if one already exists:

CODEBLOCK0

If a key is returned, use its id as --key-id for all subsequent commands. If not, create one.

2. Create a HyperLiquid Wallet

CODEBLOCK1

Returns:

• - keyId — use for all future commands
• INLINECODE13 — the EOA address (this IS the HyperLiquid account)
• INLINECODE14 — share with the user to take ownership

After creating, tell the user:

"Here is your wallet claim URL: <claimUrl>. Use this to claim ownership, set spending policies, and monitor your agent's wallet activity at https://heyvincent.ai."

Important: The wallet is empty at creation. The user must deposit USDC before trading.

3. Get Balance

CODEBLOCK2

Returns:

• - walletAddress — the EOA address
• INLINECODE17 — total perps account value in USD (cross-margin)
• INLINECODE18 — USDC available to withdraw from the perps account
• INLINECODE19 — array of open perpetual positions
• INLINECODE20 — array of spot token balances (each with coin, token, hold, total)

4. Transfer Between Perps and Spot

HyperLiquid has separate perps and spot sub-accounts. USDC must be in the correct sub-account before trading. Use internal-transfer to move USDC between them.

CODEBLOCK3

Parameters:

• - --amount: USDC amount to transfer (string, numeric)
• INLINECODE27: true = spot→perps, false = perps→spot

Response codes:

• - 200 — status: "executed" — transfer completed
• INLINECODE32 — status: "pending_approval" (human approval required by policy)
• INLINECODE34 — status: "denied" (rejected by policy)

5. Withdraw USDC to External Address

Send USDC from this HyperLiquid wallet to another HyperLiquid address via usdSend. This is an on-chain HL→HL transfer (instant, no gas).

CODEBLOCK4

Parameters:

• - --destination: Target 0x address (must be a valid 40-hex-char Ethereum address)
• INLINECODE38: USDC amount to send (string, numeric)

Response codes:

• - 200 — status: "executed" — withdrawal completed
• INLINECODE41 — status: "pending_approval" (human approval required by policy)
• INLINECODE43 — status: "denied" (rejected by policy)

6. Fund the Wallet

Deposit USDC to the EOA address via:

• - HyperLiquid bridge from Arbitrum: visit https://app.hyperliquid.xyz/portfolio and bridge USDC to the EOA address
• HL→HL transfer (usdSend) from another HL account — instant

Minimum for a BTC perp trade: $2 USDC (covers $10 notional at 20x default leverage + taker fees).

7. Browse Markets

CODEBLOCK5

Returns a JSON object mapping coin names to mid prices (e.g. {"BTC": "105234.5", "ETH": "3412.0", ...}).

8. Get Order Book

CODEBLOCK6

Returns levels — a two-element array [bids, asks]. Each entry is [price, size, numOrders]. Use levels[1][0][0] for best ask, levels[0][0][0] for best bid.

9. Place a Trade

CODEBLOCK7

Parameters:

• - --coin: Asset name (e.g. BTC, ETH, SOL)
• INLINECODE57: true for long, false for short/close
• INLINECODE60: Size in base currency (e.g. 0.0001 BTC)
• INLINECODE62: Price. For market orders, set slightly above ask (buy) or below bid (sell) to ensure fill. Recommended: askPx * 1.005 for buys, bidPx * 0.995 for sells.
• INLINECODE65: market (IoC) or limit (GTC)
• INLINECODE68: Pass when closing a position to prevent accidentally opening a new one in the opposite direction

Minimum notional: $10 (e.g. 0.0001 BTC at $100k/BTC). Default leverage is 20x cross-margin.

Response codes:

• - 200 — status: "executed" with orderId (numeric) and INLINECODE72
• INLINECODE73 — status: "pending_approval" (human approval required by policy)
• INLINECODE75 — status: "denied" (rejected by policy)

10. View Open Orders

CODEBLOCK8

11. View Trade History

CODEBLOCK9

12. Cancel Orders

CODEBLOCK10

Trading Engine: Stop-Loss, Take-Profit & Trailing Stop

The Trading Engine fully supports HyperLiquid. You can set automated stop-loss, take-profit, and trailing stop rules on any HL position. Rules execute automatically when price conditions are met — no LLM involved.

For HyperLiquid rules, use --venue hyperliquid and set --market-id / --token-id to the coin name (e.g. BTC, ETH, SOL). The --trigger-price is an absolute USD price (not 0–1 like Polymarket).

Stop-Loss

CODEBLOCK11

Sells the position if BTC drops to $95,000.

Take-Profit

CODEBLOCK12

Sells the position if ETH rises to $4,500.

Trailing Stop

CODEBLOCK13

Stop price ratchets up as SOL rises. Sells if SOL drops 5% from its peak.

Manage Rules

CODEBLOCK14

For full strategy docs (LLM-powered strategies, signal pipeline, drivers), see the Trading Engine skill.

Policies (Server-Side Enforcement)

The wallet owner controls what the agent can do by setting policies at https://heyvincent.ai. All policies are enforced server-side before any trade executes.

Policy	What it does
Spending limit (per tx)	Max USD notional per trade
Spending limit (daily)

Max USD notional per rolling 24 hours |
| Spending limit (weekly) | Max USD notional per rolling 7 days |
| Require approval | Every trade needs human approval via Telegram |
| Approval threshold | Trades above a USD amount need human approval via Telegram |

If a trade is blocked, the API returns status: "denied" with the reason. If approval is needed, status: "pending_approval" is returned and the wallet owner receives a Telegram notification.

Re-linking

If the agent loses its API key:

1. 1. User generates a re-link token from INLINECODE87
2. User gives the token to the agent
3. Agent runs:

CODEBLOCK15

Re-link tokens are one-time use and expire after 10 minutes.

Workflow Example

CODEBLOCK16

Output Format

All CLI commands return JSON to stdout.

balance:
CODEBLOCK17

markets:
CODEBLOCK18

orderbook:

{
  "coin": "BTC",
  "levels": [
    [["105200.0", "0.5", 3], ["105100.0", "1.2", 5]],
    [["105300.0", "0.3", 2], ["105400.0", "0.8", 4]]
  ]
}

levels[0] = bids (descending), levels[1] = asks (ascending). Each entry is [price, size, numOrders]. Best bid: levels[0][0][0], best ask: levels[1][0][0].

trade (executed):
CODEBLOCK20

trade (pending approval):
CODEBLOCK21

trade (denied):
CODEBLOCK22

withdraw (executed):
CODEBLOCK23

withdraw (pending approval):
CODEBLOCK24

withdraw (denied):
CODEBLOCK25

internal-transfer (executed):
CODEBLOCK26

internal-transfer (pending approval):
CODEBLOCK27

internal-transfer (denied):
CODEBLOCK28

open-orders:

{
  "walletAddress": "0x...",
  "openOrders": [
    {
      "coin": "BTC",
      "side": "B",
      "limitPx": "100000.0",
      "sz": "0.0001",
      "oid": 12345678,
      "timestamp": 1700000000000,
      "origSz": "0.0001"
    }
  ]
}

side: "B" = buy/long, "A" = ask/sell.

trades (fills):
CODEBLOCK30

cancel-order / cancel-all:

{}

Empty object on success. Any non-zero exit code indicates failure.

Error Handling

Error	Cause	Resolution
INLINECODE96	Invalid or missing API key	Check key-id is correct; re-link if needed
INLINECODE97

Trade blocked by server-side policy | User must adjust policies at heyvincent.ai | | status: "pending_approval" | Trade exceeds approval threshold | Do not retry — wallet owner receives Telegram notification to approve/deny | | 400 Bad Request | Invalid parameters (e.g. non-numeric oid, bad coin) | Fix the parameter values | | 429 Rate Limited | Too many requests | Wait and retry with backoff | | 500 TRADE_FAILED | HyperLiquid rejected the order (e.g. insufficient margin, bad price) | Check account balance and order parameters | | Key not found | API key was revoked or never created | Re-link with a new token from the wallet owner |

Important Notes

• - No gas required. HyperLiquid L1 is gasless — all perp trades settle natively.
• Perps and spot sub-accounts. The generated EOA has both a perps sub-account (cross-margin) and a spot sub-account. Use internal-transfer to move USDC between them. Deposits via the HL bridge land in the perps account by default.
• Never try to access raw secret values. The private key stays server-side.
• Always share the claim URL with the user after creating a wallet.
• For market orders, always set limitPx slightly outside the best price (* 1.005 for buys, * 0.995 for sells) to guarantee IoC fill at the current market price.
• If a trade returns status: "pending_approval", do not retry — wait for the wallet owner to respond via Telegram.