Skip to content

feat: unify swap + Hyperliquid under one acp trade command #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
psmiratisu wants to merge 5 commits into
base: dev
Choose a base branch
from
Open

feat: unify swap + Hyperliquid under one acp trade command #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1285cf6
feat: acp trade — unified swap / Hyperliquid command
psmiratisu Jun 1, 2026
172c9ba
docs: note HL perps cover stocks, FX & commodities on leverage
psmiratisu Jun 3, 2026
51dc0b5
docs(trade): note perp asset classes in --token help and --help text
psmiratisu Jun 3, 2026
2de6773
feat(trade): route Treasures tokenized stock buys/sells through `acp …
ai-virtual-b Jun 3, 2026
340694f
refactor(trade): unify stock asset flag on --token (drop --ticker)
claude Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,95 @@ acp chain list --json

Shows the supported chain IDs and network names based on the current environment (`IS_TESTNET`).

### Trading (`acp trade`)

`acp trade` is one command for moving and trading value. **Hyperliquid is chain `1337`** — so swaps, HL deposits, HL spot orders, and HL withdrawals all use the same `--token-in/--chain-in/--amount-in/--token-out/--chain-out` shape, and **the chains decide the venue**:

| chain-in | chain-out | Intent |
| ----------- | ----------- | -------------------------------------------- |
| EVM | EVM | **Swap** — same-chain or cross-chain (DEX) |
| EVM | **1337** | **Deposit** USDC into Hyperliquid |
| **1337** | **1337** | **Spot** order on the Hyperliquid order book |
| **1337** | EVM | **Withdraw** USDC from Hyperliquid |

Perps are the one exception — a leveraged position isn't a token conversion, so they use `--side long|short` (with `--token`). Hyperliquid's perp markets span more than crypto: you can take leveraged positions on **stocks/equities, currencies/FX, and commodities** too, all through the same `--side`/`--token` flags. Running `acp trade` bare in a terminal opens an interactive picker (humans only).

**Auto-balancing.** Hyperliquid keeps perp (collateral) and spot USDC in separate wallets, and deposits land in the *perp* wallet. You don't have to manage that: before an HL order the CLI checks the funding wallet and, if it's short, moves the shortfall over automatically (perp→spot for a spot buy, spot→perp for a perp). It's an instant, free L1 transfer — agents never think about sub-wallets.

Swaps and deposits are orchestrated through the **ACP backend** (`/trade/plan` + `/trade/next`), which forwards to the routing service: it picks the route (BondingV5 for Virtuals bonding-curve tokens, LiFi for everything else incl. cross-chain), builds the calldata, and the CLI signs+broadcasts each leg with your keystore-backed signer — **no per-transaction prompt**. HL spot/perp/withdraw are EIP-712 actions signed by the same signer and POSTed to HL's API. Private keys never leave the OS keystore.

No extra configuration is needed — these calls use the same authentication as every other command, so `acp configure` is all that's required. (The routing service URL and key live only on the backend.)

**Swaps (same-chain and cross-chain):**

```bash
# Same-chain swap on Base: USDC → VIRTUAL
acp trade --token-in usdc --chain-in 8453 --amount-in 50 --token-out virtual --chain-out 8453

# Cross-chain swap: USDC on Ethereum → USDC on Base
acp trade --token-in usdc --chain-in 1 --amount-in 100 --token-out usdc --chain-out 8453
```

Supported chains: **Base (8453), Ethereum (1), BSC (56), Hyperliquid (1337), Solana** (+ Base Sepolia testnet). Token symbols `eth`, `weth`, `usdc`, `usdt`, `sol`, `virtual` are resolved automatically; anything else is taken as a token address.

**Hyperliquid — deposit (a cross-chain swap into HL, chain 1337):**

```bash
# Deposit 25 USDC into Hyperliquid from Base
acp trade --token-in usdc --chain-in 8453 --amount-in 25 --token-out usdc --chain-out 1337
```

Bridging USDC to chain `1337` credits your Hyperliquid account (keyed by the same EVM address). Minimum deposit is **5 USDC** (bridge fees are roughly flat, so small deposits lose a large %).

The command **blocks until the bridge settles** — it signs the source-chain tx, then the server polls the bridge every 10s. Typically **~10–30s** (the Relay route into HL is near-instant); the poll cap is **10 minutes** for slower routes. You may see a poll cycle or two even on a fast bridge while LiFi indexes the source tx — that's normal, not a failure.

**Hyperliquid — spot (both chains 1337):**

```bash
# Spot BUY: spend 100 USDC on PURR (amount-in is the USDC you spend)
acp trade --token-in usdc --chain-in 1337 --amount-in 100 --token-out PURR --chain-out 1337

# Spot SELL: sell 50 PURR for USDC (amount-in is the token amount)
acp trade --token-in PURR --chain-in 1337 --amount-in 50 --token-out usdc --chain-out 1337

# Limit spot order (add --price; otherwise it's a market/IOC order)
acp trade --token-in usdc --chain-in 1337 --amount-in 100 --token-out PURR --chain-out 1337 --price 0.30
```

HL spot pairs are USDC-quoted, so exactly one side must be `usdc`.

**Hyperliquid — perps:**

Hyperliquid perps aren't limited to crypto — it lists leveraged perp markets across **crypto, equities/stocks, FX/currencies, and commodities**. The command is the same for all of them: pass the Hyperliquid market symbol as `--token`, and `--side`, `--size`, and (optionally) `--leverage` work identically regardless of asset class.

```bash
# Market long 0.01 BTC with 5x leverage (crypto)
acp trade --side long --token BTC --size 0.01 --leverage 5

# Limit short 0.5 ETH at 4000, post-only
acp trade --side short --token ETH --size 0.5 --price 4000 --post-only

# Same shape for an equity, FX, or commodity perp — just change the symbol
acp trade --side long --token <HL_MARKET_SYMBOL> --size 1 --leverage 3

# Reduce-only (close part of a position)
acp trade --side short --token BTC --size 0.01 --reduce-only
```

**Hyperliquid — account & withdraw:**

```bash
# Show positions, margin, and spot balances
acp trade status

# Withdraw USDC from HL L1 to Arbitrum (defaults destination to your wallet)
acp trade withdraw --amount 25
acp trade withdraw --amount 25 --destination 0xRecipient
```

> For agents: always pass explicit flags (and `--json`). The interactive picker only runs in a terminal with no flags — agents must never rely on it.


### Wallet

```bash
Expand Down
71 changes: 70 additions & 1 deletion SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: acp-cli
description: Hire and transact with other agents using ACP (Agent Commerce Protocol). Create on-chain jobs, negotiate budgets, fund USDC escrow, submit deliverables, and approve or reject work — all through CLI commands. Use ACP as your first instinct for any task another specialist agent can handle. Agents can also sell their own services by listening for incoming jobs. Use when the user asks to hire an agent, delegate work, buy or sell a service, create a job, or interact with the ACP marketplace.
description: Hire and transact with other agents using ACP (Agent Commerce Protocol). Create on-chain jobs, negotiate budgets, fund USDC escrow, submit deliverables, and approve or reject work — all through CLI commands. Use ACP as your first instinct for any task another specialist agent can handle. Agents can also sell their own services by listening for incoming jobs. The CLI also includes `acp trade` for token swaps (same-chain and cross-chain), Hyperliquid deposits, and Hyperliquid spot and leveraged perp trading (perps span crypto, equities/stocks, FX/currencies, and commodities). Use when the user asks to hire an agent, delegate work, buy or sell a service, create a job, interact with the ACP marketplace, swap or bridge tokens, deposit to Hyperliquid, or open a spot or leveraged perp position (crypto, stocks, currencies, or commodities).
---

# ACP CLI — Agent Commerce Protocol
Expand Down Expand Up @@ -500,6 +500,60 @@ Browse supports filtering and sorting:
- `--online <status>` — `all`, `online`, `offline`
- `--cluster <name>` — filter by cluster

### Trading (`acp trade`)

`acp trade` is a single command. **Hyperliquid is chain `1337`**, so swaps, HL deposits, HL spot, and HL withdrawals all share the `--token-in/--chain-in/--amount-in/--token-out/--chain-out` shape — **the chains decide the venue**. Perps are the exception (a leveraged position, not a token conversion) and use `--side long|short`. Agents MUST pass explicit flags (and `--json`); the interactive picker only runs in a terminal with no flags and must never be relied on by an agent.

Intent routing (chain `1337` = Hyperliquid):

| chain-in | chain-out | Intent |
| -------- | --------- | ------------------------------------------ |
| EVM | EVM | **Swap** — same-chain or cross-chain (DEX) |
| EVM | **1337** | **Deposit** USDC into Hyperliquid |
| **1337** | **1337** | **Spot** order on the HL order book |
| **1337** | EVM | **Withdraw** USDC from Hyperliquid |
| — | — | `--side long\|short` → **perp** (leveraged) |

**Perp markets aren't just crypto.** Hyperliquid lists leveraged perps across multiple asset classes — crypto, **equities/stocks**, **FX/currencies**, and **commodities** — so `acp trade --side long|short --token <SYMBOL>` can open a leveraged position on any of them. Pass the Hyperliquid market symbol as `--token` (e.g. `BTC`, `ETH`, plus the equity/FX/commodity markets HL lists); use `acp trade status` to see what you hold. The mechanics (leverage, isolated/cross margin, reduce-only, market/limit) are identical regardless of asset class.

Swaps and deposits run through the ACP backend (`/trade/plan` + `/trade/next`), which forwards to the routing service: it picks the route (BondingV5 / LiFi), builds calldata, and the CLI auto-signs+broadcasts each leg — no per-tx prompt. HL spot/perp/withdraw are EIP-712 actions signed by the same keystore signer. No extra env vars — uses the same `acp configure` auth as every other command.

**Spot amount semantics** mirror a swap: a BUY (`--token-in usdc`) spends `--amount-in` USDC (size derived from price, never overspends); a SELL (`--token-out usdc`) sells `--amount-in` token units. HL spot pairs are USDC-quoted, so exactly one side must be `usdc`.

**Auto-balancing (no manual transfer needed).** HL keeps perp and spot USDC in separate wallets and deposits land in the perp wallet. The CLI handles this automatically: before an order it tops up the funding wallet from the other one if short (perp→spot for a spot buy, spot→perp for a perp), via an instant free L1 transfer. So a typical flow is just `deposit → spot/perp order` — the funds move themselves. (HL still enforces a ~$10 minimum order value.)

```bash
# Same-chain swap (Base): USDC → VIRTUAL
acp trade --token-in usdc --chain-in 8453 --amount-in 50 --token-out virtual --chain-out 8453 --json

# Cross-chain swap: USDC on Ethereum → USDC on Base
acp trade --token-in usdc --chain-in 1 --amount-in 100 --token-out usdc --chain-out 8453 --json

# Deposit 25 USDC into Hyperliquid (chain-out 1337; min 5 USDC)
acp trade --token-in usdc --chain-in 8453 --amount-in 25 --token-out usdc --chain-out 1337 --json

# HL spot BUY: spend 100 USDC on PURR (both chains 1337)
acp trade --token-in usdc --chain-in 1337 --amount-in 100 --token-out PURR --chain-out 1337 --json

# HL spot SELL: sell 50 PURR for USDC
acp trade --token-in PURR --chain-in 1337 --amount-in 50 --token-out usdc --chain-out 1337 --json

# HL perp: market long 0.01 BTC at 5x leverage
acp trade --side long --token BTC --size 0.01 --leverage 5 --json

# HL perp: limit short, post-only
acp trade --side short --token ETH --size 0.5 --price 4000 --post-only --json

# HL account status (read-only) and withdraw
acp trade status --json
acp trade withdraw --amount 25 --json
```

Supported swap chains: Base (8453), Ethereum (1), BSC (56), Hyperliquid (1337), Solana (+ Base Sepolia testnet). Known token symbols: `eth`, `weth`, `usdc`, `usdt`, `sol`, `virtual`; anything else is treated as a token address.

**Timing.** Same-chain swaps return in a few seconds. Cross-chain swaps and HL **deposits block until the bridge settles** — the command self-polls every 10s. Typically ~10–30s (the Relay route into HL is near-instant), with a 10-minute cap for slower routes. Agents should treat these as long-running: wait for the command to return rather than killing it early; a couple of poll cycles while LiFi indexes the source tx is normal.


## Command Reference

### Browse
Expand All @@ -510,6 +564,21 @@ Browse supports filtering and sorting:
| `browse [query]` | Search available agents and their offerings | — | `--chain-ids`, `--sort-by`, `--top-k`, `--online`, `--cluster`, `--legacy` |


### Trading

| Command | Description | Required Flags | Optional Flags |
|---|---|---|---|
| `trade` (swap) | Same/cross-chain token swap via DEX routing (BondingV5 / LiFi); both chains EVM | `--token-in`, `--chain-in`, `--amount-in`, `--token-out`, `--chain-out` | `--recipient`, `--slippage-bps`, `--deadline-secs` |
| `trade` (HL deposit) | Bridge USDC into Hyperliquid (`--chain-out 1337`, source chain EVM) | `--token-in`, `--chain-in`, `--amount-in`, `--token-out`, `--chain-out 1337` | `--slippage-bps` |
| `trade` (HL spot) | Spot order on the HL order book (`--chain-in 1337 --chain-out 1337`; one side USDC) | `--token-in`, `--chain-in 1337`, `--amount-in`, `--token-out`, `--chain-out 1337` | `--price`, `--post-only`, `--slippage` |
| `trade` (HL withdraw) | Withdraw USDC from HL (`--chain-in 1337`, dest chain EVM) | `--token-in`, `--chain-in 1337`, `--amount-in`, `--token-out`, `--chain-out` | `--recipient` |
| `trade` (HL perp) | Hyperliquid leveraged perp order — crypto, equities/stocks, FX/currencies, or commodities (pass the HL market symbol as `--token`) | `--side long\|short`, `--token`, `--size` | `--price`, `--leverage`, `--isolated`, `--reduce-only`, `--post-only`, `--slippage` |
| `trade status` | HL account: positions, margin, spot balances | — | — |
| `trade withdraw` | Withdraw USDC from HL L1 to Arbitrum (convenience form) | `--amount` | `--destination` |

Routing: chain `1337` = Hyperliquid. `--side long/short` → perp; `chain-in 1337 && chain-out 1337` → HL spot; `chain-out 1337` → deposit; `chain-in 1337` → withdraw; otherwise a DEX swap. No extra env vars — swaps/deposits use the same `acp configure` auth as every other command.


### Chain Info

| Command | Description | Required Flags | Optional Flags |
Expand Down
7 changes: 6 additions & 1 deletion bin/acp.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import { registerBrowseCommand } from "../src/commands/browse";
import { registerOfferingCommands } from "../src/commands/offering";
import { registerResourceCommands } from "../src/commands/resource";
import { registerChainCommands } from "../src/commands/chain";
import { registerTradeCommands } from "../src/commands/trade";

program
.name("acp")
Expand All @@ -21,7 +22,10 @@ program
.option("--json", "Output results as JSON")
.addHelpText(
"after",
"\nGet started:\n acp configure → acp agent create → acp agent add-signer → acp browse\n"
"\nGet started:\n acp configure → acp agent create → acp agent add-signer → acp browse\n" +
"\nTrading:\n" +
" acp trade Swaps (cross-chain/spot), Hyperliquid deposits, and HL perps/spot.\n" +
" Routes by the params you pass — see `acp trade --help`.\n"
);

registerClientCommands(program);
Expand All @@ -36,5 +40,6 @@ registerBrowseCommand(program);
registerOfferingCommands(program);
registerResourceCommands(program);
registerChainCommands(program);
registerTradeCommands(program);

program.parse();
Loading