인증

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

토큰을 얻는 두 가지 방법

두 종류의 토큰은 모두 Bearer 토큰입니다. 발급 방식과 보유할 수 있는 스코프에서 차이가 있습니다.

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 토큰을 전송합니다. 호출을 귀하의 통합에 귀속시키려면 빌더 코드 헤더를 추가하십시오.

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

스코프

토큰은 하나 이상의 스코프를 가집니다. 서버는 엔드포인트별로 스코프를 확인하고 토큰이 허용하는 범위를 초과하는 호출을 거부합니다.

• 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와 거래

토큰 보유자는 현재 KYC 티어 한도 내에서 거래합니다. 티어 0은 주문을 넣을 수 없습니다. 티어 1은 일일 최대 100 USDC, 티어 2는 10,000 USDC까지 허용합니다.