Getting Started

Quick start guide for integrating with the trading platform

⚠️ 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 and Supported Assets.

See the Staging Environment Guide (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.

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 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

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.

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.

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.

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.

---

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 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.

---

Quick Reference

Topic	Documentation
Authentication	Authentication & Account Model
Signatures	Signatures
WebSocket Trading	WebSocket API
REST API	REST API
Error Codes	Error Codes
Order Types	Trading Concepts

---

Rate Limits

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

See Nonce & Rate Limits 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.