> For the complete documentation index, see [llms.txt](https://docs.hyperlink.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperlink.xyz/api/exchange-methods.md).

# Exchange Methods

Reference for HyperLink's unified POST /exchange endpoint: request format, action families, and Hyperliquid-compatible order and query examples used.

Every HyperLink action and read query is a `POST /exchange` request. There is no separate `/info` host. This page covers the request format and the action families; the pages below it list each method's full request and response schema.

HyperLink is a prime broker for Hyperliquid and mirrors Hyperliquid's `/exchange` action format and signing, so existing trading tooling can point at the HyperLink base URL.

## Request format

Each request uses the standard [envelope](/api/setup.md#request-envelope): an `action`, an EIP-712 `signature`, and a millisecond `nonce`. Two signing domains apply: agent-signed for trading and queries, user-signed for withdrawals and transfers. See [Authentication & Keys](/api/api-keys.md).

* **Write actions** return a status wrapper.
* **Read queries** return raw JSON.

## Example: place a limit order

A GTC limit buy of `0.1` of asset index `0`, agent-signed. Order fields use Hyperliquid's short-form names (`a` asset, `b` buy, `p` price, `s` size, `r` reduceOnly, `t` type, `c` client order id). HyperLink **requires** a `c` (cloid) on every order.

```bash
curl -X POST https://api.hyperlink.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
  "action": {
    "type": "order",
    "orders": [
      { "a": 0, "b": true, "p": "50000", "s": "0.1", "r": false, "t": { "limit": { "tif": "Gtc" } }, "c": "0x1234567890abcdef1234567890abcdef" }
    ],
    "grouping": "na"
  },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}'
```

A resting order returns its order ID:

```json
{ "status": "ok", "response": { "type": "order", "data": { "statuses": [ { "resting": { "oid": 77738308 } } ] } } }
```

An `order` action accepts up to **100 orders**. Hyperliquid enforces a notional minimum (\~$10). See the **order** method below for the full schema.

## Action families

Each method below has its full schema and examples.

### Trading

Modify replaces a resting order in place: same asset, same side, new price or size. To change side or asset, cancel and place a new order.

| Action          | Purpose                                                   |
| --------------- | --------------------------------------------------------- |
| `order`         | Place limit or trigger orders.                            |
| `modify`        | Reprice or resize one resting order.                      |
| `batchModify`   | Reprice or resize up to 100 resting orders in one action. |
| `cancel`        | Cancel resting orders by order ID (`oid`).                |
| `cancelByCloid` | Cancel resting orders by client order ID (`cloid`).       |

Both modify actions target a resting order by `oid` or `cloid`, and reject the replacement unless:

* It carries its own `c`, distinct from the target's `cloid`.
* It is `Gtc` or `Alo`. Replacements rest post-only, so one that would cross the book is rejected, not filled.
* It is not a trigger order, an `Ioc`, or a builder-code order, and omits `a` (always place).
* Any reduce-only leg is a perp and stays within the target's remaining size.

One `batchModify` carries up to 100 entries, all spot or all perp, with no duplicate targets or replacement `cloid`s. Each entry resolves independently: a rejected leg returns its own error in `statuses` while the rest proceed.

### Margin

Leverage is **per-asset** (no single global cap); margin mode cannot change with an open position.

| Action                    | Purpose                                    |
| ------------------------- | ------------------------------------------ |
| `updateLeverage`          | Set leverage and margin mode (`is_cross`). |
| `updateIsolatedMargin`    | Add or remove isolated margin.             |
| `topUpIsolatedOnlyMargin` | Set isolated margin to a target leverage.  |

### Transfers & withdrawals

Withdrawals are **user-signed** and gasless: you sign the request, HyperLink submits it on-chain for you. Agents cannot withdraw. See [Deposits & Withdrawals](/trade/deposits.md).

| Action             | Signing | Purpose                                                                 |
| ------------------ | ------- | ----------------------------------------------------------------------- |
| `withdraw`         | User    | Request a gasless on-chain withdrawal.                                  |
| `sendAsset`        | User    | Transfer funds between your own DEX balances (spot, perp).              |
| `usdClassTransfer` | User    | Move funds between spot and perp balances (legacy; prefer `sendAsset`). |
| `agentSendAsset`   | Agent   | Transfer assets with agent authorization.                               |

### Builder codes

Applications routing orders can charge a user-approved per-order fee. See [Builder Codes](/api/builder-codes.md).

| Action              | Signing | Purpose                                                                               |
| ------------------- | ------- | ------------------------------------------------------------------------------------- |
| `approveBuilderFee` | User    | Approve a maximum builder fee rate for a builder.                                     |
| `claimRewards`      | Agent   | Claim builder fees, referral cashback, and referral commissions to your spot balance. |

### Referrals

`setReferrer` links another account's referral code and grants trading access. Linking is permanent and requires an available slot. Accounts with at least $5 million in weighted lifetime Hyperliquid volume qualify without a code.

After $10,000 HyperLink weighted volume, use `registerReferrer` to create a code with 3–16 ASCII letters or digits. Codes are uppercased and start with 10 slots. Query `referral` for `cap` and `remaining`.

| Action             | Purpose                             |
| ------------------ | ----------------------------------- |
| `setReferrer`      | Bind the signer to a referral code. |
| `registerReferrer` | Register a referral code.           |

### Queries (raw JSON, agent-signed)

| Query                         | Returns                                                                |
| ----------------------------- | ---------------------------------------------------------------------- |
| `clearinghouseState`          | Perp positions, margin summary, withdrawable.                          |
| `spotClearinghouseState`      | Spot balances.                                                         |
| `openOrders`                  | Open orders.                                                           |
| `userFills`                   | Recent fills.                                                          |
| `userFillsByTime`             | Fills in an inclusive time range from the retained history.            |
| `portfolio`                   | Account value and PnL history.                                         |
| `userHistoricalOrders`        | Historical orders.                                                     |
| `userFunding`                 | Funding payments.                                                      |
| `userNonFundingLedgerUpdates` | Deposits, withdrawals, transfers.                                      |
| `userRateLimit`               | Rate-limit usage.                                                      |
| `activeAssetData`             | Per-asset leverage and margin context.                                 |
| `extraAgents`                 | Approved agents.                                                       |
| `maxBuilderFee`               | Approved builder fee rate for one builder, in tenths of a basis point. |
| `approvedBuilders`            | Builder addresses the account has approved.                            |
| `referral`                    | Referral state.                                                        |

Use `userFillsByTime` for older fills. Sign with your account or an approved agent, including a read-only agent. Pass `startTime` in milliseconds; `endTime` defaults to now. Both bounds are inclusive. Results are time-ordered, with up to 2,000 fills from the newest 10,000 retained per user. See the **userFillsByTime** method below for schemas and errors.

## Streaming

For real-time data and signed actions over a persistent connection, use the [WebSocket API](/api/websocket.md) instead of polling.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hyperlink.xyz/api/exchange-methods.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.