ArbiSpot REST API Documentation

@ArbiCare

The ArbiSpot bot provides a RESTful API to access spread data, user statistics, exchange configurations, and to send broadcasts programmatically.

Base URL

Local: http://localhost:3000/api/v1

Interactive Documentation (Swagger UI)

You can view the interactive OpenAPI documentation and test endpoints directly from your browser by navigating to: http://localhost:3000/api/docs

Authentication

Public endpoints (/spreads, /exchanges, /coins) do not require authentication. Admin endpoints require an API key to be passed in the X-API-Key header.

Header Format:

X-API-Key: <your_api_key>

The API key is defined in the .env file as API_KEY. The default key for testing is test_admin_key_123.

Public Endpoints

1. Get Current Spreads

Returns the latest calculated spreads across all active exchanges.

URL: /spreads
Method: GET
Parameters: ?userId=<id> (optional) - to apply personalized user rates

Example Response:

json
{
  "rows": [
    { "coin": "BTC", "bestAsk": 60000, "bestAskEx": "binance", "bestBid": 60500, "bestBidEx": "bybit", "grossPct": 0.83, "netPct": 0.63 }
  ],
  "exchanges": [ ... ],
  "updatedAt": "2026-04-24T18:00:00Z"
}

2. Get Public Exchanges

Returns a list of all active exchanges (used by the web app UI).

URL: /exchanges
Method: GET

Admin Endpoints (Require `X-API-Key`)

1. Get Statistics

URL: /admin/stats
Method: GET

2. Manage Users

List all users: GET /admin/users
Get specific user: GET /admin/users/:id
Update user: PATCH /admin/users/:idBody: { "tags": "vip,investor", "is_blocked": false }
Note: Send "tags": "clear" to remove all tags.

3. Broadcasts

Get history: GET /admin/broadcasts

Send new broadcast: POST /admin/broadcastsBody:json
{
  "text": "Hello <b>everyone</b>!",
  "targetType": "tags",
  "targetTags": ["vip", "ru"]
}

Resend to new users: POST /admin/broadcasts/:id/resend

4. Manage Custom Exchanges

List all (including hidden): GET /admin/exchanges
Add new: POST /admin/exchangesBody: { "id": "myex", "name": "My Exchange", "url": "https://...", "trading_fee": 0.001 }
Update: PATCH /admin/exchanges/:id
Hide/Delete: DELETE /admin/exchanges/:id
Restore: POST /admin/exchanges/:id/restore

Testing with CURL

1. Public Request:

bash
curl http://localhost:3000/api/v1/spreads

2. Authenticated Admin Request:

bash
curl -H "X-API-Key: test_admin_key_123" http://localhost:3000/api/v1/admin/stats

3. Sending a Broadcast via API:

bash
curl -X POST http://localhost:3000/api/v1/admin/broadcasts \
     -H "X-API-Key: test_admin_key_123" \
     -H "Content-Type: application/json" \
     -d '{"text": "🚨 Urgent update!","targetType": "all"}'