chore: sync from internal

Author: phantom-commit-bot[bot]

.yarn/patches/incur-npm-0.3.25-2e01dedd21.patch

@@ -0,0 +1,81 @@
+diff --git a/dist/Cli.d.ts b/dist/Cli.d.ts
+index 5c8cfeccb7595a4129d882cb8a1b94776b3d151b..fbe7e0237803be5553de268a331178ed46f81461 100644
+--- a/dist/Cli.d.ts
++++ b/dist/Cli.d.ts
+@@ -200,6 +200,15 @@ export declare namespace create {
+             agents?: string[] | undefined;
+             /** Override the command agents will run to start the MCP server. Auto-detected if omitted. */
+             command?: string | undefined;
++            /** Instructions passed to the MCP server, surfaced to the AI agent. Only effective on the root CLI. */
++            instructions?: string | undefined;
++            /** MCP tool annotations for this command. */
++            annotations?: {
++                readOnlyHint?: boolean;
++                destructiveHint?: boolean;
++                idempotentHint?: boolean;
++                openWorldHint?: boolean;
++            } | undefined;
+         } | undefined;
+         /** Options for the built-in `skills add` command. */
+         sync?: {
+diff --git a/dist/Cli.js b/dist/Cli.js
+index 1467ccf7a6eb6c2bf1e7a5172631032ea3c342e7..0ab7e87b073b3c63844cf17698df153ead4abe50 100644
+--- a/dist/Cli.js
++++ b/dist/Cli.js
+@@ -171,6 +171,7 @@ async function serveImpl(name, commands, argv, options = {}) {
+             env: options.envSchema,
+             vars: options.vars,
+             version: options.version,
++            ...(options.mcp?.instructions ? { instructions: options.mcp.instructions } : undefined),
+         });
+         return;
+     }
+diff --git a/dist/Mcp.d.ts b/dist/Mcp.d.ts
+index 19133240a3ca922693a027040510d5bb0ca143af..0383af1e3dff306c35b3bf9ea3d82618365b0827 100644
+--- a/dist/Mcp.d.ts
++++ b/dist/Mcp.d.ts
+@@ -62,6 +62,13 @@ export type ToolEntry = {
+         required?: string[];
+     };
+     outputSchema?: Record<string, unknown> | undefined;
++    annotations?: {
++        readOnlyHint?: boolean;
++        destructiveHint?: boolean;
++        idempotentHint?: boolean;
++        openWorldHint?: boolean;
++    } | undefined;
++    instructions?: string | undefined;
+     command: any;
+     middlewares?: MiddlewareHandler[] | undefined;
+ };
+diff --git a/dist/Mcp.js b/dist/Mcp.js
+index 74f218ddbad2b0febf9a33e5ea29df2a25a0fc99..15afbfd2830e31ac6eea5bae9815fb9eed1b8260 100644
+--- a/dist/Mcp.js
++++ b/dist/Mcp.js
+@@ -4,7 +4,7 @@ import * as Command from './internal/command.js';
+ import * as Schema from './Schema.js';
+ /** Starts a stdio MCP server that exposes commands as tools. */
+ export async function serve(name, version, commands, options = {}) {
+-    const server = new McpServer({ name, version });
++    const server = new McpServer({ name, version, ...(options.instructions ? { instructions: options.instructions } : undefined) });
+     for (const tool of collectTools(commands, [])) {
+         const mergedShape = {
+             ...tool.command.args?.shape,
+@@ -15,6 +15,8 @@ export async function serve(name, version, commands, options = {}) {
+             ...(tool.description ? { description: tool.description } : undefined),
+             ...(hasInput ? { inputSchema: z.object(mergedShape) } : undefined),
+             ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : undefined),
++            ...(tool.annotations ? { annotations: tool.annotations } : undefined),
++            ...(tool.instructions ? { _meta: { instructions: tool.instructions } } : undefined),
+         }, async (...callArgs) => {
+             // registerTool passes (args, extra) when inputSchema is set, (extra) when not
+             const params = hasInput ? callArgs[0] : {};
+@@ -114,6 +116,8 @@ export function collectTools(commands, prefix, parentMiddlewares = []) {
+                 ...(entry.output
+                     ? { outputSchema: Schema.toJsonSchema(entry.output) }
+                     : undefined),
++                ...(entry.mcp?.annotations ? { annotations: entry.mcp.annotations } : undefined),
++                ...(entry.mcp?.instructions ? { instructions: entry.mcp.instructions } : undefined),
+                 command: entry,
+                 ...(parentMiddlewares.length > 0 ? { middlewares: parentMiddlewares } : undefined),
+             });

README.md

@@ -30,9 +30,9 @@ import {
 // App wrapper with provider and theme configuration
 <PhantomProvider
   config={{
-    providers: ["google", "apple", "phantom", "injected"], // Allowed auth providers
+    providers: ["google", "apple", "injected"], // Allowed auth providers
     addressTypes: [AddressType.solana, AddressType.ethereum],
-    appId: "your-app-id", // Required when using embedded providers (google, apple, phantom, etc.)
+    appId: "your-app-id", // Required when using embedded providers (google, apple, etc.)
     // Optional:
     // apiBaseUrl: "https://api.phantom.app/v1/wallets",
   }}
@@ -193,7 +193,7 @@ Thin wrapper over `@phantom/browser-sdk` that provides React hooks, context prov
 
 - React hooks: `usePhantom`, `useConnect`, `useDisconnect`, `useSolana`, `useEthereum`
 - `ConnectButton` component - Ready-to-use button that handles the complete connection flow
-- Built-in connection modal with authentication providers (Google, Apple, Phantom Login, Browser Extension)
+- Built-in connection modal with authentication providers (Google, Apple, Browser Extension)
 - Theme system with `darkTheme` and `lightTheme` presets
 - Automatic mobile deeplink support for Phantom mobile app
 

packages/cli/PERPS.md

@@ -0,0 +1,217 @@
+# Perpetuals (Hyperliquid) — @phantom/cli
+
+The Phantom CLI exposes a full suite of perpetuals commands backed by [Hyperliquid](https://hyperliquid.xyz/). This document covers each command, its options, and common workflows.
+
+When running in MCP server mode (`phantom --mcp`), all commands are exposed as MCP tools under the `perps_` prefix.
+
+## Command Reference
+
+### `phantom perps markets` — MCP: `perps_markets`
+
+List all available perpetual markets on Hyperliquid with current prices, funding rates, open interest, 24h volume, max leverage, and asset IDs. Use this to discover tradeable markets and get current prices before opening positions.
+
+**Options:** none required
+
+---
+
+### `phantom perps account` — MCP: `perps_account`
+
+Get your perpetuals account balance including total account value, available balance, and withdrawable amount. The account is funded with USDC on Hyperliquid.
+
+**Options:**
+
+- `--walletId` (optional) — wallet ID, defaults to authenticated wallet
+- `--derivationIndex` (optional) — derivation index, default 0
+
+---
+
+### `phantom perps positions` — MCP: `perps_positions`
+
+Get your open perpetual positions including entry price, mark price, unrealized PnL, and margin used.
+
+**Options:**
+
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+---
+
+### `phantom perps orders` — MCP: `perps_orders`
+
+Get your open perpetual orders (resting limit orders waiting to be filled).
+
+**Options:**
+
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+---
+
+### `phantom perps history` — MCP: `perps_history`
+
+Get your perpetual trade history (filled orders).
+
+**Options:**
+
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+---
+
+### `phantom perps open` — MCP: `perps_open`
+
+Open a perpetual position on Hyperliquid. Supports market and limit orders in long or short direction. The position size is specified in USD.
+
+**Options:**
+
+- `--market` — market symbol, e.g. `BTC`, `ETH`, `SOL`
+- `--direction` — `long` or `short`
+- `--sizeUsd` — position size in USD (e.g. `100` for $100 notional)
+- `--leverage` — leverage multiplier (e.g. `1` for 1x, `10` for 10x)
+- `--orderType` — `market` or `limit`
+- `--limitPrice` (required for limit orders) — the limit price
+- `--marginType` — `isolated` (default) or `cross`
+- `--reduceOnly` (optional) — if set, can only reduce an existing position
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+**Notes:**
+
+- Run `phantom perps markets` first to verify the market symbol and current price.
+- Market orders apply a 10% slippage buffer automatically.
+- Requires USDC in the perps account. Use `phantom perps deposit` then `phantom perps transfer` if needed.
+
+---
+
+### `phantom perps close` — MCP: `perps_close`
+
+Close an open perpetual position. Submits a market order in the opposite direction to fully close the position.
+
+**Options:**
+
+- `--market` — market symbol of the position to close
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+---
+
+### `phantom perps cancel` — MCP: `perps_cancel`
+
+Cancel an open perpetual order by order ID.
+
+**Options:**
+
+- `--orderId` — the order ID to cancel
+- `--market` — market symbol of the order
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+---
+
+### `phantom perps leverage` — MCP: `perps_leverage`
+
+Update the leverage multiplier for a market without changing any positions.
+
+**Options:**
+
+- `--market` — market symbol
+- `--leverage` — new leverage multiplier
+- `--marginType` — `isolated` or `cross`
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+---
+
+### `phantom perps transfer` — MCP: `perps_transfer`
+
+Move USDC from the Hyperliquid spot account into the perpetuals account. This is an internal Hyperliquid transfer — both accounts live on Hypercore (Hyperliquid's chain).
+
+**Options:**
+
+- `--amountUsdc` — amount of USDC to transfer (e.g. `100`)
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+**Note:** USDC must already be in your Hyperliquid spot account. Use `phantom perps deposit` to bridge tokens from external chains first.
+
+---
+
+### `phantom perps deposit` — MCP: `perps_deposit`
+
+Bridge tokens from an external chain (Solana, Arbitrum, Base, Ethereum, Polygon) into Hyperliquid as USDC via a cross-chain swap. USDC is delivered to your Hyperliquid spot account. Run `phantom perps transfer` afterwards to move it into the perp account.
+
+**Options:**
+
+- `--sourceChainId` — CAIP-2 source chain ID (e.g. `solana:mainnet`, `eip155:42161` for Arbitrum, `eip155:8453` for Base)
+- `--amount` — amount to send in human-readable units (e.g. `100` for 100 USDC)
+- `--sellTokenMint` (optional) — token to sell on source chain; defaults to USDC on source chain
+- `--sellTokenIsNative` (optional) — set to sell native SOL or ETH
+- `--execute` — omit to preview quote only; pass `--execute` to sign and broadcast
+
+---
+
+### `phantom perps withdraw` — MCP: `perps_withdraw`
+
+Bridge USDC from the Hyperliquid perpetuals account to an external chain (Solana, Base, Ethereum, Arbitrum, Polygon) via the Relay bridge.
+
+**Options:**
+
+- `--amountUsdc` — amount of USDC to withdraw (e.g. `50`)
+- `--destinationChainId` — CAIP-2 destination chain (e.g. `solana:mainnet`, `eip155:8453` for Base)
+- `--buyToken` (optional) — CAIP-19 token to receive; defaults to USDC on destination chain
+- `--walletId` (optional)
+- `--derivationIndex` (optional)
+
+**Note:** Run `phantom perps account` to check the withdrawable balance before withdrawing.
+
+---
+
+## Common Workflows
+
+### Fund and open a position
+
+```bash
+# 1. Bridge USDC from Solana to Hyperliquid spot
+phantom perps deposit --sourceChainId solana:mainnet --amount 100 --execute
+
+# 2. Move USDC from Hyperliquid spot into perps account
+phantom perps transfer --amountUsdc 100
+
+# 3. Check available markets and current price
+phantom perps markets
+
+# 4. Open a long position
+phantom perps open --market BTC --direction long --sizeUsd 100 --leverage 5 --orderType market
+
+# 5. Verify the position
+phantom perps positions
+```
+
+### Close and withdraw
+
+```bash
+# 1. Check open positions
+phantom perps positions
+
+# 2. Close the position
+phantom perps close --market BTC
+
+# 3. Check withdrawable balance
+phantom perps account
+
+# 4. Bridge USDC back to Solana
+phantom perps withdraw --amountUsdc 100 --destinationChainId solana:mainnet
+```
+
+### Place and manage a limit order
+
+```bash
+# 1. Place a limit order
+phantom perps open --market ETH --direction long --sizeUsd 50 --leverage 3 --orderType limit --limitPrice 3000
+
+# 2. Check the order is on the book
+phantom perps orders
+
+# 3. Cancel the order if needed
+phantom perps cancel --orderId <orderId> --market ETH
+```