> For the complete documentation index, see [llms.txt](https://docs.arkis.xyz/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arkis.xyz/home/trade-in-defi-and-cefi/hyperliquid-trading.md).

# Hyperliquid Trading

Arkis lets your organization trade on Hyperliquid through the native Hyperliquid API, authenticated with your Arkis API key instead of a private key. You send the order you want, Arkis signs it with your organization’s dedicated signing key and delivers it to Hyperliquid.

Request and response bodies follow Hyperliquid's own format. For the full description of queries, actions and responses, see the [Hyperliquid API docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api). This page covers only what differs when you go through Arkis.

### How it works

* **Dedicated signing key.** The Arkis team creates your organization's signing key during onboarding. The key is managed by a key management service (KMS) backed by an HSM certified to FIPS 140-3 Security Level 3. Nobody, including Arkis engineers, can see or export it.
* **You never sign anything.** Send the plain, unsigned action. Arkis signs it and forwards it to Hyperliquid. Do not include a `signature` field.

The **Arkis Public API** is available at [`https://trade.arkis.xyz`](https://trade.arkis.xyz/).

| Endpoint                                 | Hyperliquid equivalent                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `POST /e/v1/trades/hyperliquid/info`     | [Info endpoint](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint)         |
| `POST /e/v1/trades/hyperliquid/exchange` | [Exchange endpoint](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint) |

### Quick start

Replace `<Token>` with your API key and `<Sub Account Address>` with the address of one of your organization's sub-accounts.

**Read account state**

```bash
curl -X POST https://trade.arkis.xyz/e/v1/trades/hyperliquid/info \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{ "type": "clearinghouseState", "user": "<Sub Account Address>" }'
```

**Place an order**

```bash
curl -X POST https://trade.arkis.xyz/e/v1/trades/hyperliquid/exchange \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "order",
      "orders": [
        { "a": 0, "b": true, "p": "50000", "s": "0.01", "r": false,
          "t": { "limit": { "tif": "Gtc" } } }
      ],
      "grouping": "na"
    },
    "nonce": 1700000000000,
    "vaultAddress": "<Sub Account Address>"
  }'
```

### Authentication

Every request carries an Arkis API key:

```
Authorization: Bearer <Token>
```

[This page](https://docs.arkis.xyz/home/for-developers/arkis-api/api-keys) includes step-by-step instructions on how to create and revoke an API key. When creating the key in the Arkis App, select the permissions you need:

| To use                                                 | Select in the UI           |
| ------------------------------------------------------ | -------------------------- |
| `/info`: read positions, orders, balances, market data | Hyperliquid (Read access)  |
| `/exchange`: place, modify and cancel orders           | Hyperliquid (Trade access) |

* An API key is bound to a single organization and its associated signing key.
* An expired or revoked key returns `401`.
* Select only the permissions you need. Keys with many permissions are larger, and total request headers must stay under 16 KB.

### Supported requests

Arkis exposes order and position management only. Anything not listed is rejected with status `403`.

| Endpoint  | Supported types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /info     | "allMids", "l2Book", "candleSnapshot", "meta", "metaAndAssetCtxs", "spotMeta", "spotMetaAndAssetCtxs", "fundingHistory", "predictedFundings", "perpDexs", "tokenDetails", "clearinghouseState", "spotClearinghouseState", "activeAssetData", "portfolio", "userRole", "userFees", "userRateLimit", "maxBuilderFee", "openOrders", "frontendOpenOrders", "orderStatus", "historicalOrders", "userFills", "userFillsByTime", "twapSliceFills", "userFunding", "userNonFundingLedgerUpdates", "vaultDetails", "userVaultEquities", "delegations", "delegatorSummary", "delegatorHistory", "delegatorRewards", |
| /exchange | "order", "cancel", "cancelByCloid", "modify", "batchModify", "scheduleCancel", "twapOrder", "twapCancel", "updateLeverage", "updateIsolatedMargin",                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

`twapCancel` additionally requires numeric `a` (asset) and `t` (TWAP id).

### Responses and errors

Hyperliquid's reply is passed through unchanged in the response body. Arkis adds meaning to the HTTP status:

| Status | Meaning                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------- |
| 200    | Hyperliquid accepted the request                                                                |
| 207    | Batch partly rejected. Check every entry in `response.data.statuses`                            |
| 400    | Malformed body. Checked before anything is signed. Fields listed under `errors`                 |
| 401    | API key missing, malformed, revoked or expired                                                  |
| 403    | Not allowed: missing permission, unsupported type, or foreign/missing sub-account. See `detail` |
| 404    | Wrong path or method                                                                            |
| 422    | Hyperliquid rejected the request. Its reply is in the body                                      |
| 431    | Request headers too large (over 16 KB)                                                          |

Errors generated by Arkis use `application/problem+json`:

```json
{
  "title": "Invalid Request Body",
  "detail": "Exchange request is malformed",
  "errors": { "action.type": ["The action.type field is required"] }
}
```

For Hyperliquid's own error messages (nonce, margin, price/size, etc.), see the [Hyperliquid docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api).

\ <br>
