> For the complete documentation index, see [llms.txt](https://docs.hyprearn.com/HnETD1HQdaN5QhTwmV4l/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyprearn.com/HnETD1HQdaN5QhTwmV4l/developers/quick-start.md).

# Quick Start

**Base URL:**

> <mark style="color:$primary;">`https://api.hyprearn.com/v1/trade`</mark>

Get an end-user from zero to trading on Hyperliquid, the default DEX. Add the <mark style="color:$primary;">`dex`</mark> parameter to a request to trade on another supported DEX. See [API Authentication](https://docs.hyprearn.com/HnETD1HQdaN5QhTwmV4l/developers/api-authentication.md) and [API Endpoints](https://docs.hyprearn.com/HnETD1HQdaN5QhTwmV4l/developers/api-endpoints.md) for full specs.

***

## How It Works

| Concept               | Role                                                          |
| --------------------- | ------------------------------------------------------------- |
| **API key**           | Your app (tenant). One key, many users.                       |
| **userWalletAddress** | End-user's EOA - stable per-user identifier.                  |
| **Smart wallet**      | HyprEarn-provisioned Arbitrum wallet per user.                |
| **API wallet**        | Hyperliquid agent wallet that executes trades.                |
| **dex**               | Target perp DEX per request. Optional. Default `hyperliquid`. |

> Flow: **deposit USDC (Arbitrum) → bridge to Hyperliquid → trade.**

### **Authentication & Rate-limit**

* <mark style="color:$primary;">`apiKey`</mark> (query, body, or <mark style="color:$primary;">`x-api-key`</mark> header)
* x402 pay-per-user
* 30 req/min

***

## Onboarding

Two-phase flow via <mark style="color:$primary;">`activate-account`</mark>. Use <mark style="color:$primary;">`get-account`</mark> to poll status (read-only, no side effects).

> ```
> activate-account  →  AWAITING_DEPOSIT  →  user deposits ≥6 USDC (Arbitrum) →  activate-account again  →  READY_TO_TRADE
> ```

{% hint style="warning" %}
Minimum deposit: **6 USDC on Arbitrum** (Hyperliquid rejects below $5). Gas is paid in USDC - no ETH needed.
{% endhint %}

{% stepper %}
{% step %}

### Check Status

```hurl
GET /get-account?apiKey=<KEY>&userWalletAddress=0x...
```

| Signal                                                       | Meaning                       |
| ------------------------------------------------------------ | ----------------------------- |
| <mark style="color:$primary;">`message`</mark> present       | Not activated                 |
| <mark style="color:$primary;">`account.balance`</mark>       | Hyperliquid withdrawable USDC |
| <mark style="color:$primary;">`phase`</mark> (from activate) | Onboarding state              |
| {% endstep %}                                                |                               |

{% step %}

### Create & Activate Account

```hurl
POST /activate-account?apiKey=<KEY>&userWalletAddress=0x...
```

**First call** - provisions smart wallet + mappings:

```json
{ "phase": "AWAITING_DEPOSIT", "account": { "walletAddress": "0xsmart...", "balance": 0 } }
```

Show <mark style="color:$primary;">`account.walletAddress`</mark> → user sends **≥ 6 USDC on Arbitrum**.

**Second call** - bridges USDC to Hyperliquid, approves agent, enables trading:

| <mark style="color:$primary;">`AWAITING_DEPOSIT`</mark>             | User hasn't funded yet                                                                                                        |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$primary;">`LOW_BALANCE_AWAITING_DEPOSIT`</mark> | Top up; retry. Check <mark style="color:$primary;">`bridgeTxHash`</mark> / <mark style="color:$primary;">`bridgeError`</mark> |
| <mark style="color:$primary;">`READY_TO_TRADE`</mark>               | Start trading                                                                                                                 |

{% hint style="info" %}
Each <mark style="color:$primary;">`userWalletAddress`</mark> is scoped to the API key that onboarded it.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Trading

**Requires:**

* Phase: <mark style="color:$primary;">`READY_TO_TRADE`</mark>
* Valid API key
* Mapped <mark style="color:$primary;">`userWalletAddress`</mark>

### Supported DEXs

Every trade endpoint accepts an optional <mark style="color:$primary;">`dex`</mark> parameter. If you omit it, the request runs on Hyperliquid. Existing integrations keep working without any change.

| `dex` value   | DEX                  | Status               |
| ------------- | -------------------- | -------------------- |
| `hyperliquid` | Hyperliquid          | Default              |
| `lighter`     | Lighter (Ethereum)   | Available on request |
| `lighter_rh`  | Lighter on Robinhood | Available on request |
| `pacifica`    | Pacifica             | Available on request |
| `nado`        | Nado                 | Available on request |
| `avantis`     | Avantis              | Available on request |
| `paradex`     | Paradex              | Available on request |

{% hint style="info" %}
Symbol format, deposit asset, minimum deposit, and onboarding steps are specific to each DEX. The values on this page describe Hyperliquid. Contact the [**HyprEarn**](https://hyprearn.com/) team to enable another DEX for your API key.
{% endhint %}

**Symbol format:** `TOKEN/USDC:USDC` (e.g. `BTC/USDC:USDC`)

### Open Position

#### Endpoint

```hurl
POST /open-position
```

#### Request Parameters

```json
{
  "userWalletAddress": "0xabc...def",
  "dex": "hyperliquid",
  "symbol": "BTC/USDC:USDC",
  "type": "market",
  "side": "buy",
  "amount": 100,
  "leverage": 5,
  "marginMode": "cross",
  "orderParams": { "takeProfitPrice": 61500, "stopLossPrice": 59000 }
}
```

* <mark style="color:$primary;">`dex`</mark>: optional, default hyperliquid
* <mark style="color:$primary;">`type`</mark>: market | limit
* <mark style="color:$primary;">`side`</mark>: buy | sell
* <mark style="color:$primary;">`leverage`</mark>: 1–100
* <mark style="color:$primary;">`price`</mark> required for limit orders.

### Monitor Positions / Orders

```hurl
GET /get-available-tokens?apiKey=<KEY>
GET /get-open-positions?apiKey=<KEY>&userWalletAddress=0x...
GET /get-open-orders?apiKey=<KEY>&userWalletAddress=0x...
```

### Manage Position / Order

<table><thead><tr><th width="161.01171875">Action</th><th>Endpoint</th><th>Notes</th></tr></thead><tbody><tr><td>Close</td><td><code>POST /close-position</code></td><td>Omit <mark style="color:$primary;"><code>amount</code></mark> to close full position</td></tr><tr><td>Cancel</td><td><code>POST /cancel-order</code></td><td>Needs <mark style="color:$primary;"><code>orderId</code></mark> + <mark style="color:$primary;"><code>symbol</code></mark></td></tr><tr><td>Edit TP/SL</td><td><code>POST /update-tp-sl</code></td><td>Pair <mark style="color:$primary;"><code>tpOrderId</code></mark> + <mark style="color:$primary;"><code>takeProfitPrice</code></mark> or <mark style="color:$primary;"><code>slOrderId</code></mark>+<mark style="color:$primary;"><code>stopLossPrice</code></mark></td></tr></tbody></table>

***

## Endpoint Reference

<table><thead><tr><th width="208.67578125">Endpoint</th><th width="108.15234375">Method</th><th width="121.859375">User wallet</th><th>Purpose</th></tr></thead><tbody><tr><td><mark style="color:$primary;"><code>get-account</code></mark></td><td>GET</td><td>Required</td><td>Poll onboarding status and balance</td></tr><tr><td><mark style="color:$primary;"><code>activate-account</code></mark></td><td>POST</td><td>Required</td><td>Provision wallet, bridge, enable trading</td></tr><tr><td><mark style="color:$primary;"><code>get-available-tokens</code></mark></td><td>GET</td><td>-</td><td>List tradable perp markets</td></tr><tr><td><mark style="color:$primary;"><code>open-position</code></mark></td><td>POST</td><td>Required</td><td>Open a perp position</td></tr><tr><td><mark style="color:$primary;"><code>get-open-positions</code></mark></td><td>GET</td><td>Required</td><td>List open positions</td></tr><tr><td><mark style="color:$primary;"><code>get-open-orders</code></mark></td><td>GET</td><td>Required</td><td>List open orders</td></tr><tr><td><mark style="color:$primary;"><code>close-position</code></mark></td><td>POST</td><td>Required</td><td>Close or reduce a position</td></tr><tr><td><mark style="color:$primary;"><code>cancel-order</code></mark></td><td>POST</td><td>Required</td><td>Cancel a pending order</td></tr><tr><td><mark style="color:$primary;"><code>update-tp-sl</code></mark></td><td>POST</td><td>Required</td><td>Edit take-profit / stop-loss</td></tr></tbody></table>

### Full Endpoint Documentation

For complete request/response schemas, see the [API Endpoints](https://docs.hyprearn.com/HnETD1HQdaN5QhTwmV4l/developers/api-endpoints.md) reference.