Skip to main content
This page walks you through a minimum viable interaction with the Hyperoru API — from anonymous outsider to authenticated user listing your own traders. If you are new to REST APIs, follow along with curl and then try the same calls from the language of your choice.

​
1. Verify the service is up

Public health checks do not need a token: 
curl https://api.production.hyperoru.com/api/health
Expected response: 
{ "status": "healthy" }
If this returns anything other than 200 OK, check status.hyperoru.com before continuing.

​
2. Log in

Get a session token using the credentials you set up in the app. Replace the email and password below: 
curl -X POST https://api.production.hyperoru.com/api/users/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "a-strong-password" }'
Copy the session_token value from the response. You will attach it to every subsequent request. See Authentication for rotation and security guidance.

​
3. Look at your profile

Your first authenticated call — this confirms the token works: 
curl https://api.production.hyperoru.com/api/users/profile \
  -H "Authorization: Bearer $TOKEN"

​
4. List your AI traders

Each Hyperoru user can own multiple AI traders. Here is how to list them: 
curl https://api.production.hyperoru.com/api/account/list \
  -H "Authorization: Bearer $TOKEN"
If you have not created one yet, the list is empty. Create one through the app, or with: 
curl -X POST https://api.production.hyperoru.com/api/account/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BTC Trend Trader",
    "llm_provider": "openai",
    "llm_model": "gpt-4o"
  }'

​
5. Query the market

Market data endpoints also require authentication. Fetch the current BTC price: 
curl "https://api.production.hyperoru.com/api/crypto/price?symbol=BTC" \
  -H "Authorization: Bearer $TOKEN"

​
6. Subscribe to real-time updates

For live prices, decisions, and system events, open a WebSocket connection instead of polling: 
wss://api.production.hyperoru.com/ws?session_token=YOUR_SESSION_TOKEN
See the full protocol on the WebSocket page.

​
Common patterns

The API expects JSON bodies. Forgetting Content-Type: application/json returns 400 Bad Request with a body about invalid JSON.
List endpoints accept page, per_page, limit, and time-range filters. The exact names are documented on each endpoint page — click Try it to see the form.
5xx responses and 429 indicate a transient issue. Retry with exponential backoff (1s, 2s, 4s, …) and a small jitter. Never retry on 4xx other than 429.
New accounts return empty lists for trades, orders, and positions. Your integration should treat empty arrays as a normal state, not an error.

​
Next steps

Errors and rate limits

The full list of status codes and what they mean.

WebSocket streams

How to get live updates instead of polling.

Interactive reference

Browse every endpoint with live Try it forms.

Core concepts

Traders, strategies, signals, and decisions — explained in plain English.