> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/based-mcp.md).

# Based MCP

Trade Hyperliquid from your agent. Add one URL, sign in once in the browser, and ask in plain language. There is no API key to create.

**Endpoint:** `https://gateway.based.one/mcp`\
**Transport:** Streamable HTTP\
**Auth:** OAuth, scope `trade` (account reads and live orders)

## Before you connect

You need a Based account with funds on Hyperliquid. The first time a wallet is used, the sign-in page asks you to:

1. Deposit on Hyperliquid, if the address has no account yet.
2. Approve the Based builder fee. One signature.
3. Create an API wallet named for Based MCP. One signature. Based stores that key; your wallet key stays with you.

Sign in with email, Google, a browser wallet, or the Based mobile app (scan the QR, or use **Continue on phone**).

You can attach up to 10 wallets before you press **Allow**. Consent covers exactly the wallets on that screen.

## Connect

Use Streamable HTTP. A client that opens the URL as SSE will not connect: this server answers tool calls on `POST` only.

Request scope `trade` only. Any other scope is rejected.

### Claude Code

Run this in a terminal, outside a Claude session:

```sh
claude mcp add --scope user --transport http based https://gateway.based.one/mcp
```

`--scope user` registers it for every project. Omit that flag to keep it in the current project only.

Start Claude Code, run `/mcp`, select **based**, and choose **Authenticate**. Finish sign-in in the browser.

### Codex

Run this in a terminal:

```sh
codex mcp add based --url https://gateway.based.one/mcp
```

### Hermes

Add this to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  based:
    url: "https://gateway.based.one/mcp"
    auth: oauth
    oauth:
      scope: trade
```

Then, from a terminal:

```sh
hermes mcp login based
```

Approve the link in the browser. Start a new session, or run `/reload-mcp` in one that is already open.

Hermes registers itself. You do not create an OAuth app.

### OpenClaw

```sh
openclaw mcp add based \
  --url https://gateway.based.one/mcp \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope trade

openclaw mcp login based
```

`--transport streamable-http` is required. Without a transport, OpenClaw uses SSE.

Finish the browser sign-in, then confirm with:

```sh
openclaw mcp doctor based --probe
```

### Any other MCP client

Add `https://gateway.based.one/mcp` as a remote Streamable HTTP server and complete the OAuth sign-in the client opens. The client registers itself and stores the token. No local bridge and no header secret.

## What to ask

Start with a read, then trade:

* “Which wallets are connected, and what are their accounts?”
* “What’s my balance and open positions?”
* “What’s BTC at, and what’s the minimum size?”
* “Buy 0.01 BTC with a 10% take-profit and a 5% stop.”
* “Cancel my open BTC order.”

| Tool              | What it does                                                                  |
| ----------------- | ----------------------------------------------------------------------------- |
| `get_accounts`    | Wallets on this connection, and each wallet’s trading accounts                |
| `get_balance`     | Account value, margin, and spot balances                                      |
| `get_positions`   | Open perp positions                                                           |
| `get_open_orders` | Resting orders, including ones you placed elsewhere                           |
| `get_markets`     | Symbols, size precision, and mark price. Perps are `BTC`; spot is `HYPE/USDC` |
| `place_order`     | Limit or market order. Optional take-profit and stop-loss on perps            |
| `place_tp_sl`     | Take-profit or stop-loss on an existing perp position                         |
| `cancel_order`    | Cancel one resting order. Cancelling an entry also cancels its attached TP/SL |
| `get_order`       | Status of one order placed through Based                                      |

The agent must pass a `wallet_address` from `get_accounts` and an `account_id` from that wallet. Sizes and prices are decimal strings (`"0.01"`, `"60000"`).

## While it trades

Orders are live on Hyperliquid. Confirm size, side, and price before you let the agent send.

Saying “buy” twice places two orders. If a placement comes back unknown, ask the agent to check that order with `get_order` before placing it again.

Take-profit and stop-loss apply to perps. Attach them on the entry, or add them later to a position you already hold.

Your client refreshes access on its own. Sign in again when it asks — that is expected after the connection sits unused for about a month.

## Disconnect

Remove the server in the client. That stops new calls:

```sh
claude mcp remove based
```

```sh
openclaw mcp logout based && openclaw mcp unset based
```

In Hermes, disable or delete the `based` entry under `mcp_servers`, then `/reload-mcp`.

The API wallet approved during setup remains on the account until you revoke it on Hyperliquid.