身分驗證

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).

兩種取得 Token 的方式

兩種 Token 都是 Bearer Token。它們在鑄造方式和可攜帶的範圍上有所不同。

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.

每次交易呼叫所需的標頭

所有已驗證的呼叫都發送 Bearer Token。當您希望呼叫計入您的整合時，請新增建構者代碼標頭。

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

範圍

Token 攜帶一個或多個範圍。伺服器按端點檢查範圍，並拒絕超出 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 與交易

Token 持有者在其當前 KYC 等級的限額內交易。等級 0 無法下委託。等級 1 允許每日最多 100 USDC 的活動；等級 2 提升至 10,000 USDC。