> For the complete documentation index, see [llms.txt](https://docs.buoy.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buoy.finance/for-vault-leaders/trading-agent.md).

# Trading Agent

The **trading agent** is the key that lets you trade your vault's capital. It's a HyperCore **API wallet**: an address registered against your vault's trading account on Hyperliquid. Trades signed by the agent execute on the **vault's** account — the agent itself never holds funds and can never withdraw them.

Registering an agent is the **required final step** after creating a vault. Until it's done, your vault cannot trade.

## Setting up your agent

Open your vault → **Manage** tab → **Trading setup** panel. You have two options:

### Option A — Generate a keypair (recommended)

The app generates a fresh keypair **locally in your browser**:

* The **address** is registered on-chain as your vault's agent.
* The **secret key** is shown to you **exactly once**. Save it in a password manager immediately.

{% hint style="danger" %}
**We don't store your key. Save it now — it's shown only once.** If you lose the secret, your funds are safe (the agent can't move them), but you won't be able to trade until you rotate to a new agent — which you can do at any time, for free.
{% endhint %}

### Option B — Use your own address

Paste an address you control. Important restriction: HyperCore requires the agent to be a **fresh address with no existing Hyperliquid account** — an address that has ever been used on Hyperliquid is silently rejected (the EVM transaction still succeeds, which is exactly why the app checks eligibility for you before you submit).

Either way, registration is a single transaction.

## Agent status

The card reads the agent's live state from both HyperEVM and HyperCore and shows one of:

| State                | What it means                                                                      | What to do                                             |
| -------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Registered**       | An agent is set on the vault and live on HyperCore.                                | Nothing — you're trading.                              |
| **Not set up**       | No agent has been registered yet.                                                  | Register one.                                          |
| **Setup unfinished** | An agent address is set on the vault, but HyperCore never accepted it.             | Re-run the registration.                               |
| **Expired**          | The agent's HyperCore validity window closed; trading is down until it's replaced. | Register a new agent — the card shows the expiry date. |

{% hint style="info" %}
**A brand-new vault needs its first deposit before an agent can register.** HyperCore only recognizes an account once capital has actually landed on it, and the creation seed is bridged asynchronously. If registration doesn't take right away, wait for the seed (or your first deposit) to settle and try again — the protocol also retries automatically in the background.
{% endhint %}

## Agent validity and automatic renewal

HyperCore agent approvals expire. Buoy registers agents with the maximum validity HyperCore allows — **180 days** — and the protocol runs a background sweep that **re-registers your agent automatically** whenever HyperCore stops recognizing it. In practice a lapsed approval is restored within minutes and you never notice.

You only need to act when the app tells you the agent is **expired** — that means the automatic path couldn't restore it (for example the vault has no HyperCore account yet), and a fresh registration from your side is required.

## Trading with the agent

The agent secret is what you plug into your trading tooling:

* **professional trading terminals** that support API-wallet login — the Manage view includes a step-by-step connection guide for the terminals Buoy whitelists (see [Trading & Managing Capital](/for-vault-leaders/trading-and-capital.md));
* the **Hyperliquid API / SDKs** — sign orders with the agent key, and they execute on your vault's account;
* your own bots and scripts.

The one field everyone gets wrong: the **account** you connect is the **vault's address**, not your wallet's. The vault *is* its own HyperCore account — Buoy vaults are not native Hyperliquid vaults.

## Rotating the agent

You can replace the agent at any time (compromised key, lost secret, moving to new infrastructure) from the same card — one transaction registers the new agent. Rotation never touches the vault's funds or depositors' shares, and costs nothing but gas.

{% hint style="warning" %}
**Rotation isn't instantaneous revocation.** HyperCore has no "remove agent" action, so an old approval is displaced rather than deleted, and the protocol's background sweep evicts any leftover approval for the address you rotated away from. That happens within minutes, not seconds. If you're rotating because a key was **compromised**, rotate immediately and then watch the vault's positions until the old key is confirmed dead — and remember the worst it can do is trade, never withdraw.
{% endhint %}

## What an agent can and cannot do

| Can                                                         | Cannot                        |
| ----------------------------------------------------------- | ----------------------------- |
| Place and cancel orders on the vault's account              | Withdraw funds anywhere       |
| Trade perps (default DEX, HIP-3 and HIP-4 markets) and spot | Transfer the vault's shares   |
| —                                                           | Change vault settings or fees |

Even a fully compromised agent key cannot extract funds from the vault — the worst case is unauthorized *trading*, which you cut off by rotating the agent. This is what makes it safe to paste the key into a third-party terminal; never paste your **wallet's** private key anywhere.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.buoy.finance/for-vault-leaders/trading-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.