การยืนยันตัวตน

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 แตกต่างกันที่วิธีสร้างและ scope ที่รองรับ

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 ที่ทุก trading call ต้องการ

การเรียกทั้งหมดที่ยืนยันตัวตนส่ง bearer token เพิ่ม header รหัสผู้สร้างเมื่อต้องการให้นับการเรียกให้กับการรวมระบบของคุณ

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

Scope

Token มี scope หนึ่งหรือมากกว่า เซิร์ฟเวอร์ตรวจสอบ scope ต่อ endpoint และปฏิเสธการเรียกที่เกินกว่าที่ 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 ปัจจุบัน Tier 0 ไม่สามารถส่งออร์เดอร์ Tier 1 อนุญาตกิจกรรมรายวันสูงสุด 100 USDC Tier 2 เพิ่มเป็น 10,000 USDC