Autentikasi

How to obtain a token (Day-1 integration)

The shortest path to authenticate a bot: register a SatoriEx account from the web UI, complete Tier-1 KYC (email + phone), and exchange your password for an access token via the /auth/login endpoint. The example below uses curl so it's language-agnostic.

1. 1. Create a SatoriEx account + complete Tier-1 KYC

   Open https://staging.satoriex.io, sign up with email + password, verify your email, and complete the phone verification. Tier-1 KYC is required before any trading endpoint will accept your token. Tier-2 (government ID) is required for withdrawals.

2. 2. Exchange credentials for an access token

   POST your email and password to /api/v1/auth/login. The response carries an access_token (the JWT bearer you'll use on every authenticated call) and a refresh_token (use to mint a new access_token without re-entering the password).

   curl -sX POST https://staging.satoriex.io/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"[email protected]","password":"…"}'
   
   # Response:
   # {
   #   "code": 0,
   #   "data": {
   #     "access_token": "eyJhbGciOiJSUzI1NiI…",   # the bearer JWT
   #     "refresh_token": "…",                       # use to refresh access_token
   #     "user": { … }
   #   }
   # }

3. 3. Use the access token on every authenticated call

   Send the token in the Authorization header. The same header works on /me/balance, /orders, /me/positions, and every other authenticated endpoint. The /ws WebSocket accepts the token in the URL ?token=… parameter — see the WebSocket events page.

   # Use the access_token as a bearer
   curl -s https://staging.satoriex.io/api/v1/me/balance \
     -H "Authorization: Bearer $ACCESS_TOKEN"

4. 4. Refresh the token before it expires

   Access tokens are short-lived. When you get a 401 with code 2002 (token expired), POST the refresh_token to /api/v1/auth/refresh to mint a new access_token. The refresh_token itself rotates — store the new one each time.

   curl -sX POST https://staging.satoriex.io/api/v1/auth/refresh \
     -H "Content-Type: application/json" \
     -d '{"refresh_token":"…"}'

OAuth-style third-party flows (for clients acting on behalf of another SatoriEx user) use the /oauth/authorize authorization-code flow instead — see the OAuth-access row in the table below.

POST /orders response — 202 Accepted

When you place an order, the server responds with 202 Accepted (not 200 OK). The response includes your order object with trades set to an empty array — the order is queued for matching, not instantly filled. Fill notifications arrive asynchronously via WebSocket (order.updated events).

Dua cara mendapatkan token

Kedua jenis token adalah bearer token. Perbedaannya pada cara penerbitannya dan cakupan yang dapat dibawanya.

PAT holders earn 10 BPS maker rebate on limit fills (vs 5 BPS standard).

Personal Access Tokens (PAT)

PATs are long-lived credentials you create from your account settings at /me/personal-access-tokens. They are passed in the same Authorization: Bearer header as session tokens. PAT holders earn an enhanced maker rebate of 10 BPS (0.10%) on limit-order fills — double the 5 BPS standard rate.

# Create a PAT
curl -sX POST https://staging.satoriex.io/api/v1/me/personal-access-tokens \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-bot","scopes":["orders:write","portfolio:read"]}'

# List PATs
curl -s https://staging.satoriex.io/api/v1/me/personal-access-tokens \
  -H "Authorization: Bearer $SESSION_TOKEN"

Revoking tokens

Three paths to revoke access, depending on what you want to invalidate:

• 1.Session JWT — POST /api/v1/auth/logout. Invalidates the current session immediately.
• 2.Single PAT — DELETE /api/v1/me/personal-access-tokens/:id. Revokes one token by its ID.
• 3.OAuth grant — DELETE /api/v1/me/oauth-grants/:id. Revokes all access for a third-party client that was granted OAuth access.

Header yang diperlukan setiap panggilan perdagangan

Semua panggilan terautentikasi mengirim bearer token. Tambahkan header kode builder saat Anda ingin panggilan dikreditkan ke integrasi Anda.

Authorization: Bearer eyJhbGciOiJSUzI1NiI...   # RS256-signed JWT — session or OAuth access token
Content-Type: application/json
# Session tokens are RS256-signed JWTs. Public key available at /.well-known/jwks.json

Cakupan

Token membawa satu atau lebih cakupan. Server memeriksa cakupan per endpoint dan menolak panggilan yang melebihi izin token.

• markets:read — view market data, prices, and order books.
• markets:propose — submit new market proposals.
• orders:write — place, cancel, and manage orders.
• portfolio:read — view your positions, balances, and trade history.

KYC dan perdagangan

Pemegang token berdagang hingga batas tingkat KYC mereka saat ini. Tingkat 0 tidak dapat memasang order. Tingkat 1 memungkinkan aktivitas harian hingga 100 USDC; Tingkat 2 meningkatkannya menjadi 10.000 USDC.