Integration Guide - RcoinX Platform API

Overview

This guide walks through a typical frontend integration: register a user, authenticate, call a protected endpoint, and subscribe to realtime data.

Prerequisites

HTTP client (fetch, axios, or similar)
RcoinX API base URL (production or development)
Optional: WebSocket client for market data

Base URLs

Environment	REST API	WebSocket
Production	`https://api.rcoinx.com`	`wss://ws.poolthewool.com/ws`
Development	`http://localhost:8080`	Check your local config

Step 1: Register or Log In

curl -X POST https://api.rcoinx.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "username": "trader1"
  }'

Or log in with existing credentials:

curl -X POST https://api.rcoinx.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

The response includes access_token and refresh_token. Store them securely (memory or httpOnly cookies — never localStorage for production).

Step 2: Call Protected Endpoints

Attach the access token to subsequent requests:

curl https://api.rcoinx.com/api/profile \
  -H "Authorization: Bearer <access_token>"

See Authentication for token refresh and session handling.

Step 3: Handle MFA When Required

Some actions require a second factor. When MFA is needed, the API returns a challenge response. Complete verification using the flow in MFA and MFA Client Handlers.

Step 4: Connect to WebSocket

For realtime market data, open a WebSocket connection and subscribe to channels:

const ws = new WebSocket('wss://ws.poolthewool.com/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'ticker:BTCUSDT',
    id: 1
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  // handle ticker, kline, or trade updates
};

See the WebSocket Quickstart and Channels Guide for full details.

Error Handling

All API responses use a consistent envelope:

{
  "code": 400,
  "message": "Validation failed",
  "error": "email is required"
}

Handle common status codes:

Code	Meaning	Action
401	Unauthorized	Refresh token or redirect to login
403	Forbidden	Check permissions or MFA status
429	Rate limited	Back off and retry
500	Server error	Retry with exponential backoff

Next Steps

User Management

Auth, profile, MFA, and sessions

Asset & Balance

Balances and asset operations

WebSocket API

Realtime market data

Quickstart

Make your first API call

​Overview

​Prerequisites

​Base URLs

​Step 1: Register or Log In

​Step 2: Call Protected Endpoints

​Step 3: Handle MFA When Required

​Step 4: Connect to WebSocket

​Error Handling

​Next Steps