API Evangelist enhancements for the MAX Exchange V3 RESTful API

# generated: '2026-08-25'
# method: generated
# source: openapi/maicoin-max-v3-openapi.json
# Captures API Evangelist's enhancements to MaiCoin's published contract WITHOUT mutating it.
# Every action below adds information that the original Swagger 2.0 document omits but that
# MaiCoin documents in prose. Applying this overlay does not change any endpoint, parameter or
# schema — it only makes already-published facts machine-readable.
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the MAX Exchange V3 RESTful API
  version: 1.0.0
extends: ../openapi/maicoin-max-v3-openapi.json
actions:
- target: $.info
  description: >-
    Add the contact and licence/terms information the contract omits. Values are MaiCoin's own,
    taken from its llms.txt (max@maicoin.com) and its published terms of use.
  update:
    contact:
      name: MAX Exchange
      email: max@maicoin.com
      url: https://campaign.maicoin.com/en/api-document
    termsOfService: https://assets.maicoin.com/max/MAX-Terms-of-Use.pdf
- target: $.info
  description: >-
    Record the external documentation surfaces MaiCoin publishes but does not reference from the
    contract itself.
  update:
    x-documentation:
      api_reference: https://max-api.maicoin.com/doc/v3.html
      overview: https://campaign.maicoin.com/en/api
      websocket: https://maicoin.github.io/max-websocket-docs/
      llms_txt: https://max-api.maicoin.com/llms.txt
      status_endpoint: https://status-api-max.maicoin.com/api/status/max-api
- target: $
  description: >-
    Declare the HMAC API-key authentication as a first-class security definition. The contract
    currently expresses this only as three untyped header parameters repeated on 42 operations,
    which no code generator or scorer reads as authentication. Documented by MaiCoin in prose.
  update:
    securityDefinitions:
      MaxAccessKey:
        type: apiKey
        name: X-MAX-ACCESSKEY
        in: header
        description: The account Access Key issued at https://max.maicoin.com/api_tokens
      MaxPayload:
        type: apiKey
        name: X-MAX-PAYLOAD
        in: header
        description: Base64 encoding of the JSON request parameters merged with a `path` field and a millisecond `nonce`.
      MaxSignature:
        type: apiKey
        name: X-MAX-SIGNATURE
        in: header
        description: Hex HMAC-SHA256 of the payload string, keyed by the account Secret Key.
- target: $
  description: >-
    Record the published rate limits at the document level. MaiCoin states these in its API
    reference but the contract carries no rate-limit information at all.
  update:
    x-rate-limits:
      public:
        limit: 1200
        window: 1 minute
        scope: per-ip
      private:
        limit: 1200
        window: 1 minute
        scope: per-account
      response_headers: []
      note: No RateLimit-* or Retry-After headers are returned on REST. Verified by live probe 2026-08-25.
- target: $
  description: >-
    Record the idempotency semantics of client_oid at document level so an agent can find them
    without reading the property description on individual operations.
  update:
    x-idempotency:
      key_field: client_oid
      scope: per-account
      retention: 24 hours
      behaviour: reject-duplicate
      replays_original_response: false
      applies_to_operations:
      - postApiV3WalletPathWalletTypeOrder
      - deleteApiV3Order
      note: >-
        Order surface only. Withdrawals, transfers, loans, repayments and conversions accept no
        client key and have no duplicate protection.
- target: $.paths['/api/v3/withdrawal'].post
  description: Flag the crypto withdrawal operation as irreversible so an agent escalates before calling it.
  update:
    x-consequence: irreversible
    x-reversal-operation: null
    x-agent-guidance: >-
      One-way door. No cancel, void or recall operation exists. Requires explicit human
      confirmation in any autonomous deployment.
- target: $.paths['/api/v3/withdrawal/twd'].post
  description: Flag the TWD fiat withdrawal operation as irreversible.
  update:
    x-consequence: irreversible
    x-reversal-operation: null
    x-agent-guidance: One-way door. No reversal operation is published.
- target: $.paths['/api/v3/convert'].post
  description: Flag currency conversion as irreversible.
  update:
    x-consequence: irreversible
    x-reversal-operation: null
    x-agent-guidance: >-
      No cancel or reverse operation. Reversing economically requires a second conversion at the
      then-current rate, which carries fresh market risk.
- target: $.paths['/api/v3/wallet/{path_wallet_type}/order'].post
  description: Record the reversal path and the asynchronous acceptance semantics for order submission.
  update:
    x-consequence: reversible
    x-reversal-operation: deleteApiV3Order
    x-reversal-window: >-
      No stated duration. Cancellable while the order remains open; a cancel may race a partial
      fill because matching is asynchronous.
    x-agent-guidance: >-
      A 200 means the request was ACCEPTED, not that the order was placed. Confirm with
      GET /api/v3/order or a WebSocket order_update subscription before acting on the result.
      Read base_unit_precision, quote_unit_precision, min_base_amount and min_quote_amount from
      GET /api/v3/markets before composing volume and price.
- target: $
  description: >-
    Declare the 429 response that the contract omits on every operation, despite MaiCoin
    documenting a hard 1200/minute limit and enforcing it with an automatic IP ban.
  update:
    x-undeclared-responses:
      '429':
        description: Rate limit exceeded. Documented in prose; declared on zero operations in the contract.
        applies_to: all operations
      '401':
        description: Authentication failed. Declared only on GET /api/v3/deposit_address, though all 42 private operations can return it.
        applies_to: all private operations
- target: $
  description: Record the companion event surface, which the REST contract does not reference.
  update:
    x-event-surface:
      protocol: websocket
      endpoint: wss://max-stream.maicoin.com/ws
      documentation: https://maicoin.github.io/max-websocket-docs/
      asyncapi: ../asyncapi/maicoin-max-websocket-asyncapi.yml
      note: The AsyncAPI document is generated by API Evangelist from MaiCoin's channel docs, not provider-published.