> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/getting-started.md).

# Getting Started

> **⚠️ SDK Coming Soon**
>
> We are developing an official SDK that will simplify signature creation, payload encoding, and API integration. The manual integration steps below will remain supported but are intended primarily for advanced use cases. Stay tuned for SDK updates!

> **Environment**
>
> All examples in this documentation target the **production + mainnet (Monad)** environment unless otherwise specified. For testnet/staging endpoints, contracts, EIP-712 domains, and instrument IDs, see [Supported Chains](/developer-tools/supported-chains.md) and [Supported Assets](/developer-tools/supported-assets.md).
>
> See the [Staging Environment Guide](https://github.com/perps-core/rust-services/tree/main/external-docs/developer-tools/staging-environment.md) *(coming soon)* for staging + testnet API documentation. Staging APIs are backward compatible.

## Overview

The trading platform provides gasless perpetual futures trading using EIP-712 and EIP-191 cryptographic signatures. All operations are authenticated with wallet signatures - no API keys or passwords required.

**Key Features:**

* Gasless trading (no gas fees for orders)
* One wallet = one account (auto-created)
* WebSocket for real-time trading and execution reports
* REST API for account management and historical data
* Public market data feed (no authentication required)

***

## Integration Flow

### 1. Connect to Market Data (Optional)

Public market data is available without authentication.

**Endpoint**: `wss://marketdata.app.hello.trade/ws`

Subscribe to real-time market data:

* Light tickers (prices, volumes, 24h stats)
* Partial order book
* Candles (OHLCV data)

No authentication required. See market data documentation for details.

### 2. App-Access Gate (Invite-Code Required)

The trading platform is invite-gated. A wallet that has not been granted app access cannot authenticate against trading endpoints — `POST /api/margin/deposit` (and every other authed write) returns:

```
HTTP 403
{ "error": "USER_NOT_INVITED: this wallet has not been granted app access. Apply a referral code via POST /api/referral/apply." }
```

On WebSocket trading, the same condition surfaces as error code **4015 `USER_NOT_INVITED`**.

```typescript
const res = await fetch(
  `https://api.app.hello.trade/api/user/access-status/${walletAddress.toLowerCase()}`
);
const { hasAppAccess } = await res.json() as { hasAppAccess: boolean };
```

#### Apply an invite code

If `hasAppAccess` is `false`, submit your invite code via `POST /api/referral/apply`. The endpoint is signed (viem `personal_sign` over a canonical-JSON payload that inlines the request body) and replay-protected by a unique `x-nonce` plus a 5-minute timestamp window.

On `201`, your wallet immediately has app access and can authenticate. On `422`, the response carries an `error` string — one of `ALREADY_REFERRED`, `CODE_NOT_FOUND`, `CODE_REVOKED`, `CODE_EXHAUSTED`, or `SELF_REFERRAL`.

See [REST API — POST /api/referral/apply](/developer-tools/rest-api/authenticated-endpoints.md#post-apireferralapply) for the full payload format, headers, error codes, and a TypeScript example.

***

### 3. Authenticate with Wallet

Sign an EIP-191 message to establish your trading session.

**WebSocket**: `wss://api.app.hello.trade/ws`

```javascript
const nonce = Date.now();
const message = `${walletAddress}:${nonce}`;
const signature = await signer.signMessage(message);

// Encode the payload (see Signatures documentation for encoding details)
const encodedPayload = encodeSimpleSignaturePayload({ account: walletAddress, nonce, deadline });

// Send via WebSocket
{
  "type": "authenticate",
  "signature": {
    "sig": signature,
    "payload": encodedPayload  // Hex-encoded with type discriminator
  }
}
```

Your account is automatically created on first authentication, provided the wallet has app access (see Step 2). See [Authentication & Account Model](/developer-tools/authentication-and-account-model.md).

### 4. Manage Collateral

Deposit and withdraw USDC collateral via REST API using EIP-712 signatures.

**REST API**: `https://api.app.hello.trade/api`

* Deposits use ERC-2612 permit (gasless approval + transfer)
* Withdrawals require EIP-712 signature

See [REST API - Authenticated Endpoints](/developer-tools/rest-api/authenticated-endpoints.md).

### 5. Trade

Place, modify, and cancel orders via WebSocket using EIP-712 signatures.

Supported order types:

* Limit, StopLimit, StopLoss, TakeProfit
* Time in force: GTC, GTD, IOC, FOK, DAY

See [WebSocket API - Trading Operations](/developer-tools/websocket-api/trading-operations.md).

### 6. Monitor Execution Reports

Subscribe to real-time execution reports for order updates, fills, and account events.

After `subscribeTrading`, receive:

* Order status changes
* Trade executions
* Margin operations (deposits, withdrawals, leverage updates)
* Liquidations and funding payments

See [Execution Reports](/developer-tools/websocket-api/execution-reports.md).

***

## API Endpoints

### Trading APIs

| Service           | Endpoint                          | Authentication  |
| ----------------- | --------------------------------- | --------------- |
| WebSocket Trading | `wss://api.app.hello.trade/ws`    | EIP-191/EIP-712 |
| REST API          | `https://api.app.hello.trade/api` | EIP-712         |

### Market Data API

| Service               | Endpoint                              |
| --------------------- | ------------------------------------- |
| WebSocket Market Data | `wss://marketdata.app.hello.trade/ws` |

**Note:** Market data does not require wallet authentication.

***

## Chain Configuration

HelloTrade runs on Monad. Use the parameters for the network you are targeting. Testnet values correspond to the staging environment.

| Parameter        | Testnet (Monad)                              | Mainnet (Monad)                              |
| ---------------- | -------------------------------------------- | -------------------------------------------- |
| Chain ID         | `10143`                                      | `143`                                        |
| Vault contract   | `0xfA6fcb77ACA7F941861F8Ee0Fb40662A5B28B77b` | `0xe52B14240514E7A05DddA336cFF0D99ce8bB7230` |
| Collateral token | `0xd1eC521d1A49A1590b6ed06ed7d96dabA24E28C1` | `0x754704bc059f8c67012fed69bc8a327a5aafb603` |

### EIP-712 Domains

EIP-712 signatures require domain-specific parameters. Use the column matching your target network.

**Vault Domain** (Orders, Withdrawals, Leverage, Cancels):

| Field               | Testnet (Monad)                              | Mainnet (Monad)                              |
| ------------------- | -------------------------------------------- | -------------------------------------------- |
| `name`              | `HelloVault`                                 | `HelloVault`                                 |
| `version`           | `1`                                          | `1`                                          |
| `chainId`           | `10143`                                      | `143`                                        |
| `verifyingContract` | `0xfA6fcb77ACA7F941861F8Ee0Fb40662A5B28B77b` | `0xe52B14240514E7A05DddA336cFF0D99ce8bB7230` |

**Token Domain** (Deposits via ERC-2612):

| Field               | Testnet (Monad)                              | Mainnet (Monad)                              |
| ------------------- | -------------------------------------------- | -------------------------------------------- |
| `name`              | `UsdcMock`                                   | `USDC`                                       |
| `version`           | `1`                                          | `2`                                          |
| `chainId`           | `10143`                                      | `143`                                        |
| `verifyingContract` | `0xd1eC521d1A49A1590b6ed06ed7d96dabA24E28C1` | `0x754704bc059f8c67012fed69bc8a327a5aafb603` |

See [Signatures](/developer-tools/signatures.md) for signature construction details.

***

## Key Concepts

### Precision & Encoding

| Type         | Precision           | Example                                |
| ------------ | ------------------- | -------------------------------------- |
| **Prices**   | 18 decimals         | `500.00` → `"500000000000000000000"`   |
| **USDC**     | 6 decimals          | `1000.00` → `"1000000000"`             |
| **Quantity** | Instrument-specific | `100 NVDA` → `"10000000"` (5 decimals) |
| **Leverage** | × 100               | `10x` → `1000`                         |

### Timestamps

Nonces and event timestamps use **milliseconds**; signed `deadline` fields use **seconds**:

```
Date.now() → 1705600000000
```

### Nonces

Two types of nonces:

* **Wallet nonce**: `Date.now()` for most operations
* **Token nonce**: Fetch from token contract for deposits

See [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md).

***

## Quick Reference

| Topic             | Documentation                                                                          |
| ----------------- | -------------------------------------------------------------------------------------- |
| Authentication    | [Authentication & Account Model](/developer-tools/authentication-and-account-model.md) |
| Signatures        | [Signatures](/developer-tools/signatures.md)                                           |
| WebSocket Trading | [WebSocket API](/developer-tools/websocket-api.md)                                     |
| REST API          | [REST API](/developer-tools/rest-api.md)                                               |
| Error Codes       | [Error Codes](/developer-tools/error-codes.md)                                         |
| Order Types       | [Trading Concepts](/about/trading/order-types.md)                                      |

***

## Rate Limits

| Limit                 | Value                       |
| --------------------- | --------------------------- |
| Requests per second   | 20 per authenticated wallet |
| WebSocket connections | 8 per account               |
| Idle timeout          | 30 seconds                  |

See [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md) for details.

***

## Common Data Types

| Type      | Description                          | Example                     |
| --------- | ------------------------------------ | --------------------------- |
| `Address` | Ethereum address                     | `"0x742d35Cc6634..."`       |
| `string`  | String representation of decimal/qty | `"42000.50"`                |
| `U256`    | Unsigned 256-bit integer (as string) | `"42000000000000000000000"` |
| `u64`     | Unsigned 64-bit integer              | `1705600000000`             |

***

## Support

For questions or issues, please contact support or file an issue in the documentation repository.