身份验证

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。