# Overview (/docs/risex/api)

# RISE API Usage Examples

This page gets you trading on RISEx in a few lines of TypeScript using the community `risex-client` SDK. For complete API documentation, refer to the [Full API Documentation](https://developer.rise.trade/reference/general-information).

## Base URL

```
https://developer.rise.trade/reference/general-information
```

## Quickstart

The fastest way to get started is with [`risex-client`](https://www.npmjs.com/package/risex-client), a community-maintained TypeScript SDK that handles EIP-712 signing, bitmap nonces, and rate limiting for you.

> **Note:** `risex-client` is an **unofficial** community SDK. It is not maintained or endorsed by the RISEx team. For production use, consider integrating against the [Full API](https://developer.rise.trade/reference/general-information) directly.

### Install

```bash
npm install risex-client
```

Requires Node.js 18+.

### Get an API signer key

1. Open the [RISEx web app](https://rise.trade) and go to **API** in the header
2. Create a new API Wallet and store the private key
3. Set environment variables:

```bash
ACCOUNT_ADDRESS=0x...        # your wallet address
SIGNER_PRIVATE_KEY=0x...     # the API signer private key
```

### Read-only: fetch markets and orderbook

`InfoClient` exposes all public read endpoints — no keys required.

```typescript
import { InfoClient } from 'risex-client';

const info = new InfoClient();

const markets = await info.getMarkets();
for (const m of markets) {
  console.log(`${m.display_name}: ${m.last_price}`);
}

const book = await info.getOrderbook(1); // BTC-PERP
console.log('Best bid:', book.bids[0]?.price);
console.log('Best ask:', book.asks[0]?.price);
```

### Trading: place and close a position

`ExchangeClient` is the authenticated client. Always call `await client.init()` before any authenticated method — it fetches the EIP-712 domain and contract addresses from the API.

```typescript
import { ExchangeClient } from 'risex-client';

const client = new ExchangeClient({
  account: process.env.ACCOUNT_ADDRESS,
  signerKey: process.env.SIGNER_PRIVATE_KEY,
});

await client.init();

// Market buy on ETH-PERP (market_id=2), 1 step = 0.001 ETH
const order = await client.marketBuy(2, 1);
console.log('Filled:', order.order_id, 'tx:', order.tx_hash);

// Inspect the resulting position
const pos = await client.info.getPosition(2, client.account);
if (pos) {
  console.log('Position:', pos.size, pos.side === 0 ? 'Long' : 'Short');
}

// Close it
await client.closePosition(2);
```

Sizes use integer **steps** and prices use integer **ticks** — see `market.config.step_size` and `market.config.step_price` for the conversion factors.

### Streaming: subscribe to orderbook updates

```typescript
import { WebSocketClient } from 'risex-client';

const ws = new WebSocketClient();

ws.onChannel('orderbook', (msg) => {
  const data = msg.data as {
    bids?: Array<{ price: string; quantity: string }>;
    asks?: Array<{ price: string; quantity: string }>;
  };
  if (data.bids?.[0]) console.log('Top bid:', data.bids[0].price);
  if (data.asks?.[0]) console.log('Top ask:', data.asks[0].price);
});

await ws.connect();
ws.subscribe({ channel: 'orderbook', market_ids: [1] }); // BTC-PERP
```

Available channels: `orderbook`, `trades`, `orders`, `positions`, `oracle`, `ticker`.

## Full API Documentation

For complete API documentation including:

* All request/response schemas

* Authentication requirements

* Rate limits

* WebSocket endpoints

* Error codes

* Link to Full API - [https://developer.rise.trade/reference/general-information](https://developer.rise.trade/reference/general-information)

* Link to TS SDK - [https://www.npmjs.com/package/risex-client](https://www.npmjs.com/package/risex-client)