Maicoin Authentication

generated: '2026-08-25'
method: searched
source: https://max-api.maicoin.com/api/doc/external/v3 (info.description, "身分驗證" section) + https://maicoin.github.io/max-websocket-docs/authentication.md
docs: https://campaign.maicoin.com/en/api-document
note: >-
  DERIVATION FAILED, SEARCH SUCCEEDED. The published contract is Swagger 2.0 and declares NO
  securityDefinitions block at all, so derive-authentication.py produced zero profiles. The three
  auth headers are instead declared as ordinary per-operation header PARAMETERS on all 42 private
  operations (X-MAX-ACCESSKEY / X-MAX-PAYLOAD / X-MAX-SIGNATURE), which no scorer or code generator
  will read as a security scheme. The model below is transcribed from MaiCoin's own prose docs.
  This is a concrete, cheap fix for MaiCoin: declaring one apiKey securityDefinition and a global
  `security` block would make the same auth machine-readable without changing a single endpoint.
schemes:
- id: max-hmac
  type: apiKey
  in: header
  applies_to: MAX Exchange REST API v3 (42 of 54 operations)
  headers:
  - name: X-MAX-ACCESSKEY
    description: The account's Access Key, issued from the API token management page.
  - name: X-MAX-PAYLOAD
    description: Base64 encoding of the JSON request parameters merged with a `path` field.
  - name: X-MAX-SIGNATURE
    description: Hex HMAC-SHA256 of the payload string, keyed by the account's Secret Key.
  - name: X-Sub-Account
    required: false
    description: Selects a sub-account to operate on. Defaults to the main account, "main".
  algorithm: HMAC-SHA256
  signing:
    steps:
    - Build a parameter object containing `nonce` (Unix epoch milliseconds) plus the request parameters.
    - Merge the request `path` into that object as a `path` field.
    - JSON-serialise the merged object.
    - Base64-encode the JSON string. This is X-MAX-PAYLOAD.
    - HMAC-SHA256 the payload string using the Secret Key; hex-encode the digest. This is X-MAX-SIGNATURE.
    parameter_transport: GET appends parameters to the query string; POST/PUT/DELETE send them in the JSON body. The signed payload must match either way.
  replay_protection:
    mechanism: nonce
    unit: milliseconds since Unix epoch
    max_clock_skew_seconds: 30
    single_use: true
    note: 'Each nonce may be used only once and must be within 30 seconds of server time. The WebSocket surface returns error 1006 for skew and 1012 for reuse.'
- id: max-websocket-auth
  type: apiKey
  in: message
  applies_to: MAX Exchange WebSocket API (private channels)
  action: auth
  fields:
  - apiKey
  - nonce
  - signature
  - id
  - filters
  algorithm: HMAC-SHA256
  signing:
    note: >-
      DIFFERENT FROM REST. The WebSocket signature is the hex HMAC-SHA256 of the NONCE STRING ALONE,
      keyed by the API secret — not of a base64 payload. A client that reuses the REST signing routine
      here will fail with error 1007 (authentication failed). This divergence is undocumented as a
      divergence; it is only visible by reading both pages.
  success_event: authenticated
  filters:
    default: [order, trade, account]
    available: [order, trade, account, trade_update, fast_trade_update, mwallet_order, mwallet_trade, mwallet_fast_trade_update, mwallet_account, ad_ratio, borrowing]
- id: none
  type: none
  applies_to: MAX Exchange REST API v3 public endpoints (12 of 54 operations) and all public WebSocket channels
  note: 'Public market data — markets, currencies, timestamp, k, depth, trades, tickers, ticker, and the four m-wallet public index/limit/interest endpoints — needs no credentials. Verified live: GET /api/v3/markets returned 200 unauthenticated on 2026-08-25.'
credential_issuance:
  url: https://max.maicoin.com/api_tokens
  prerequisites:
  - A registered MAX account (https://max.maicoin.com/signup)
  - Completed identity verification
  permissions_model: >-
    Tokens carry per-scope read permissions selected at creation time. The WebSocket docs name
    "read permission for Order / Trade" and "read permission for Account & Personal Information"
    as separate grants. MaiCoin publishes no enumerated machine-readable permission list, so
    scopes/ is intentionally absent — this is key auth, not OAuth.
oauth2: false
openid_connect: false
mutual_tls: false
security_guidance:
  published:
  - Do not share API keys.
  - Rotate API keys periodically.
  - Configure an IP allow-list for additional security.
  source: MAX V3 API reference, "安全指南" section