openapi: 3.0.3
info:
  title: OMNIAXS External API
  version: 1.0.0
  description: |
    OMNIAXS Global Hub 外部接口规范（v1）。
    对应 PRD_v1.1_zh，包含市场、交易、账户、状态与 Waitlist 接口。
    国际化基线：支持 zh-CN / en-US / ja-JP，默认 en-US。
servers:
  - url: https://sandbox-api.pincermarket.com
    description: Sandbox
  - url: https://api.pincermarket.com
    description: Production
tags:
  - name: Public
  - name: Identity
  - name: Access
  - name: System
  - name: Market
  - name: Trading
  - name: Account
  - name: Admin
security:
  - ApiKeyAuth: []
paths:
  /public/v1/waitlist:
    post:
      tags: [Public]
      summary: Submit waitlist lead
      operationId: submitWaitlist
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitlistRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitlistResponse'
        '403':
          description: Geo-fence blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/register:
    post:
      tags: [Identity]
      summary: Register user account
      operationId: registerUser
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegisterRequest'
      responses:
        '200':
          description: User registration accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/resend-verification:
    post:
      tags: [Identity]
      summary: Resend email verification code
      operationId: resendUserVerificationCode
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailOnlyRequest'
      responses:
        '200':
          description: Verification code re-sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/verify-email:
    post:
      tags: [Identity]
      summary: Verify user email with one-time code
      operationId: verifyUserEmail
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserVerifyEmailRequest'
      responses:
        '200':
          description: Email verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: Invalid or expired code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/login:
    post:
      tags: [Identity]
      summary: Start user login challenge (password validated, OTP sent by email)
      operationId: loginUser
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLoginRequest'
      responses:
        '200':
          description: Login challenge created, OTP required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Email not verified or user disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/login/resend-otp:
    post:
      tags: [Identity]
      summary: Resend user login OTP for an active challenge
      operationId: resendUserLoginOtp
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLoginOtpResendRequest'
      responses:
        '200':
          description: Login OTP re-sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: Challenge invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/login/verify-otp:
    post:
      tags: [Identity]
      summary: Verify user login OTP and issue access/refresh tokens
      operationId: verifyUserLoginOtp
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLoginOtpVerifyRequest'
      responses:
        '200':
          description: OTP verified and login success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: OTP invalid, expired, or challenge invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/auth/refresh:
    post:
      tags: [Identity]
      summary: Refresh user token pair
      operationId: refreshUserToken
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRefreshRequest'
      responses:
        '200':
          description: Refreshed token pair
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '401':
          description: Session invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/user/me:
    get:
      tags: [Identity]
      summary: Get current user profile
      operationId: getUserProfile
      security:
        - UserBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '401':
          description: Invalid user token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/user/api-keys:
    get:
      tags: [Identity]
      summary: List API keys for current user
      operationId: listUserApiKeys
      security:
        - UserBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: API key list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
    post:
      tags: [Identity]
      summary: Create API key for current user
      operationId: createUserApiKey
      security:
        - UserBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserApiKeyCreateRequest'
      responses:
        '200':
          description: API key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/user/api-keys/{key_id}:
    delete:
      tags: [Identity]
      summary: Revoke API key for current user
      operationId: revokeUserApiKey
      security:
        - UserBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/IdempotencyKey'
        - in: path
          name: key_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: API key revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '404':
          description: API key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/admin/auth/register:
    post:
      tags: [Identity]
      summary: Register admin account and send email verification code
      operationId: registerAdmin
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminRegisterRequest'
      responses:
        '200':
          description: Admin registration accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/admin/auth/resend-verification:
    post:
      tags: [Identity]
      summary: Resend admin email verification code
      operationId: resendAdminVerificationCode
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailOnlyRequest'
      responses:
        '200':
          description: Verification code re-sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '404':
          description: Admin not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/admin/auth/verify-email:
    post:
      tags: [Identity]
      summary: Verify admin email with one-time code
      operationId: verifyAdminEmail
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminVerifyEmailRequest'
      responses:
        '200':
          description: Admin email verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: Invalid or expired code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/admin/auth/login:
    post:
      tags: [Identity]
      summary: Start admin login challenge (password validated, OTP sent by email)
      operationId: loginAdmin
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminLoginRequest'
      responses:
        '200':
          description: Admin login challenge created, OTP required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '401':
          description: Invalid admin credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Email not verified or admin disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/admin/auth/login/resend-otp:
    post:
      tags: [Identity]
      summary: Resend admin login OTP for an active challenge
      operationId: resendAdminLoginOtp
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminLoginOtpResendRequest'
      responses:
        '200':
          description: Admin login OTP re-sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: Challenge invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /public/v1/admin/auth/login/verify-otp:
    post:
      tags: [Identity]
      summary: Verify admin login OTP and issue bearer token
      operationId: verifyAdminLoginOtp
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminLoginOtpVerifyRequest'
      responses:
        '200':
          description: OTP verified and admin login success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '422':
          description: OTP invalid, expired, or challenge invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/v1/admin/users:
    get:
      tags: [Admin]
      summary: List platform users
      operationId: adminListUsers
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: keyword
          schema:
            type: string
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /internal/v1/admin/users/{user_id}/status:
    patch:
      tags: [Admin]
      summary: Update user account status
      operationId: adminUpdateUserStatus
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/IdempotencyKey'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUserStatusUpdateRequest'
      responses:
        '200':
          description: User status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/v1/admin/users/{user_id}/api-keys:
    get:
      tags: [Admin]
      summary: List API keys of target user
      operationId: adminListUserApiKeys
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User API key list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/v1/admin/audit-events:
    get:
      tags: [Admin]
      summary: Query audit events
      operationId: adminListAuditEvents
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: query
          name: actor_type
          schema:
            type: string
        - in: query
          name: action_prefix
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: Audit event list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /public/v1/connectors/catalog:
    get:
      tags: [Identity]
      summary: List public connector catalog
      operationId: listPublicConnectorCatalog
      security: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: query
          name: provider_type
          schema:
            type: string
        - in: query
          name: stage
          schema:
            type: string
        - in: query
          name: region
          schema:
            type: string
      responses:
        '200':
          description: Connector catalog list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /internal/v1/admin/connectors/catalog:
    get:
      tags: [Admin]
      summary: List connector catalog (admin)
      operationId: adminListConnectorCatalog
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: query
          name: provider_type
          schema:
            type: string
        - in: query
          name: stage
          schema:
            type: string
        - in: query
          name: region
          schema:
            type: string
      responses:
        '200':
          description: Connector catalog list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
    post:
      tags: [Admin]
      summary: Create connector catalog record
      operationId: adminCreateConnectorCatalog
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/IdempotencyKey'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorCatalogUpsertRequest'
      responses:
        '200':
          description: Connector created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '409':
          description: Connector already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/v1/admin/connectors/catalog/{connector_id}:
    patch:
      tags: [Admin]
      summary: Update connector catalog record
      operationId: adminUpdateConnectorCatalog
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/IdempotencyKey'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: connector_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorCatalogUpsertRequest'
      responses:
        '200':
          description: Connector updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'
        '404':
          description: Connector not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /internal/v1/registry/exchanges:
    get:
      tags: [Admin]
      summary: List exchange registry records
      operationId: adminListRegistryExchanges
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Exchange registry list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /v1/access-applications:
    post:
      tags: [Access]
      summary: Submit exchange access application
      operationId: submitAccessApplication
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessApplicationCreateRequest'
      responses:
        '200':
          description: Submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessApplicationSubmitResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags: [Access]
      summary: List access applications for current tenant
      operationId: listAccessApplications
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: status
          schema:
            type: string
            enum: [submitted, reviewing, approved, rejected, provisioning, active]
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Application list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessApplicationListResponse'

  /v1/access-applications/{application_id}:
    get:
      tags: [Access]
      summary: Get access application detail
      operationId: getAccessApplication
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: path
          name: application_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Application detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessApplicationDetailResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/access-bindings:
    get:
      tags: [Access]
      summary: List active tenant exchange bindings
      operationId: listAccessBindings
      parameters:
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
      responses:
        '200':
          description: Binding list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessBindingListResponse'

  /internal/v1/admin/access-applications:
    get:
      tags: [Admin]
      summary: Admin list of all access applications
      operationId: adminListAccessApplications
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: exchange_code
          schema:
            type: string
        - in: query
          name: market
          schema:
            type: string
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Admin application list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessApplicationListResponse'

  /internal/v1/admin/access-applications/{application_id}/approve:
    post:
      tags: [Admin]
      summary: Approve access application and trigger provisioning
      operationId: adminApproveAccessApplication
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: application_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminApproveRequest'
      responses:
        '200':
          description: Approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminActionResponse'

  /internal/v1/admin/access-applications/{application_id}/reject:
    post:
      tags: [Admin]
      summary: Reject access application
      operationId: adminRejectAccessApplication
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: application_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminRejectRequest'
      responses:
        '200':
          description: Rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminActionResponse'

  /internal/v1/admin/exchange-credentials:
    post:
      tags: [Admin]
      summary: Upsert exchange platform credential
      operationId: adminUpsertExchangeCredential
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminExchangeCredentialUpsertRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminActionResponse'

  /internal/v1/admin/provisioning/jobs/{job_id}:
    get:
      tags: [Admin]
      summary: Get provisioning job detail
      operationId: adminGetProvisioningJob
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: job_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Provisioning job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisioningJobResponse'

  /internal/v1/admin/connectors/availability:
    get:
      tags: [Admin]
      summary: List connector availability status
      operationId: adminListConnectorAvailability
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Connector status list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /internal/v1/admin/connectors/{connector}/availability:
    patch:
      tags: [Admin]
      summary: Update connector availability
      operationId: adminUpdateConnectorAvailability
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: path
          name: connector
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorAvailabilityUpdateRequest'
      responses:
        '200':
          description: Updated connector status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /internal/v1/admin/alerts:
    get:
      tags: [Admin]
      summary: List admin alerts
      operationId: adminListAlerts
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
        - in: query
          name: code
          schema:
            type: string
        - in: query
          name: severity
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: Alert list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /internal/v1/admin/observability/summary:
    get:
      tags: [Admin]
      summary: Get super-admin observability summary
      operationId: adminObservabilitySummary
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Runtime and business summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /internal/v1/admin/notifications/config:
    get:
      tags: [Admin]
      summary: Get SMTP notification configuration status
      operationId: adminNotificationConfig
      security:
        - AdminBearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - in: header
          name: X-PM-ROLE
          required: true
          schema:
            type: string
      responses:
        '200':
          description: SMTP configuration status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessResponse'

  /v1/status:
    get:
      tags: [System]
      summary: Get platform system status
      operationId: getSystemStatus
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
      responses:
        '200':
          description: Status payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Error401'

  /v1/markets:
    get:
      tags: [Market]
      summary: List market instruments
      operationId: listMarkets
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: asset_class
          schema:
            type: string
            enum: [equity, fx, crypto, futures, metals, prediction, index]
        - in: query
          name: venue
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
            enum: [active, halted]
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Market instruments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketsResponse'
        '401':
          $ref: '#/components/responses/Error401'

  /v1/quotes:
    get:
      tags: [Market]
      summary: Get quote snapshots
      operationId: getQuotes
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: symbols
          required: true
          schema:
            type: string
          description: Comma-separated symbols, e.g. AAPL.US,TSLA.US
        - in: query
          name: depth
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 1
      responses:
        '200':
          description: Quotes payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesResponse'
        '401':
          $ref: '#/components/responses/Error401'

  /v1/bars:
    get:
      tags: [Market]
      summary: Get historical bars
      operationId: getBars
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: symbol
          required: true
          schema:
            type: string
        - in: query
          name: timeframe
          required: true
          schema:
            type: string
            enum: [1m, 5m, 15m, 1h, 1d]
        - in: query
          name: start
          schema:
            type: string
            format: date-time
        - in: query
          name: end
          schema:
            type: string
            format: date-time
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 200
      responses:
        '200':
          description: Bars payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarsResponse'
        '401':
          $ref: '#/components/responses/Error401'

  /v1/calendar:
    get:
      tags: [Market]
      summary: Get market session calendar
      operationId: getCalendar
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: venue
          schema:
            type: string
        - in: query
          name: asset_class
          schema:
            type: string
        - in: query
          name: date
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Calendar payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarResponse'

  /v1/orders:
    post:
      tags: [Trading]
      summary: Place order
      operationId: placeOrder
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceOrderRequest'
      responses:
        '200':
          description: Order accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '409':
          description: Business conflict (risk/session/idempotency)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          description: Connector unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags: [Trading]
      summary: Query orders
      operationId: listOrders
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: status
          schema:
            type: string
            enum: [new, partially_filled, filled, canceled, rejected]
        - in: query
          name: symbol
          schema:
            type: string
        - in: query
          name: strategy_id
          schema:
            type: string
        - in: query
          name: start
          schema:
            type: string
            format: date-time
        - in: query
          name: end
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'

  /v1/orders/batch:
    post:
      tags: [Trading]
      summary: Place batch orders
      operationId: placeBatchOrders
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchOrderRequest'
      responses:
        '200':
          description: Batch result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOrderResponse'

  /v1/orders/{order_id}:
    patch:
      tags: [Trading]
      summary: Amend order
      operationId: amendOrder
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
        - in: path
          name: order_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmendOrderRequest'
      responses:
        '200':
          description: Order amended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/orders/cancel:
    post:
      tags: [Trading]
      summary: Cancel orders
      operationId: cancelOrders
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelOrderRequest'
      responses:
        '200':
          description: Cancel result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'

  /v1/positions:
    get:
      tags: [Account]
      summary: Get positions
      operationId: getPositions
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
        - in: query
          name: symbol
          schema:
            type: string
        - in: query
          name: asset_class
          schema:
            type: string
      responses:
        '200':
          description: Position list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionsResponse'

  /v1/accounts:
    get:
      tags: [Account]
      summary: Get account overview
      operationId: getAccountOverview
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XPmTimestamp'
        - $ref: '#/components/parameters/XPmSignature'
      responses:
        '200':
          description: Account snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-PM-API-KEY
    AdminBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    UserBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
        enum: [zh-CN, en-US, ja-JP]
        default: en-US
      description: Preferred response language
    XPmTimestamp:
      name: X-PM-TIMESTAMP
      in: header
      required: true
      schema:
        type: string
      description: Unix timestamp in milliseconds
    XPmSignature:
      name: X-PM-SIGNATURE
      in: header
      required: true
      schema:
        type: string
      description: Hex signature using HMAC-SHA256
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 72
      description: Required for write operations
    PageSize:
      name: page_size
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    PageToken:
      name: page_token
      in: query
      required: false
      schema:
        type: string

  responses:
    Error401:
      description: Authentication failed
      headers:
        Content-Language:
          schema:
            type: string
            enum: [zh-CN, en-US, ja-JP]
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Error429:
      description: Rate limited
      headers:
        Content-Language:
          schema:
            type: string
            enum: [zh-CN, en-US, ja-JP]
        X-RateLimit-Limit:
          schema:
            type: string
        X-RateLimit-Remaining:
          schema:
            type: string
        X-RateLimit-Reset:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    EmailOnlyRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

    UserRegisterRequest:
      type: object
      required: [email, password, display_name, company_name, country_region]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
          maxLength: 128
        display_name:
          type: string
          minLength: 1
          maxLength: 128
        company_name:
          type: string
          minLength: 1
          maxLength: 160
        country_region:
          type: string
          minLength: 2
          maxLength: 64
        preferred_language:
          type: string
          enum: [zh-CN, en-US, ja-JP]
          default: en-US

    UserVerifyEmailRequest:
      type: object
      required: [email, verification_code]
      properties:
        email:
          type: string
          format: email
        verification_code:
          type: string
          minLength: 4
          maxLength: 16

    UserLoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 1
          maxLength: 128

    UserLoginOtpVerifyRequest:
      type: object
      required: [email, challenge_id, otp_code]
      properties:
        email:
          type: string
          format: email
        challenge_id:
          type: string
          minLength: 8
          maxLength: 64
        otp_code:
          type: string
          minLength: 4
          maxLength: 16

    UserLoginOtpResendRequest:
      type: object
      required: [email, challenge_id]
      properties:
        email:
          type: string
          format: email
        challenge_id:
          type: string
          minLength: 8
          maxLength: 64

    UserRefreshRequest:
      type: object
      required: [refresh_token]
      properties:
        refresh_token:
          type: string
          minLength: 16

    UserApiKeyCreateRequest:
      type: object
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 128
          default: default
        scopes:
          type: array
          items:
            type: string
        expires_in_days:
          type: integer
          minimum: 1
          maximum: 3650
          nullable: true

    AdminLoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 1
          maxLength: 128
        role:
          type: string
          minLength: 2
          maxLength: 64
          default: super_admin

    AdminRegisterRequest:
      type: object
      required: [email, password, display_name]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
          maxLength: 128
        display_name:
          type: string
          minLength: 1
          maxLength: 128
        role:
          type: string
          enum: [ops_admin, compliance_admin]
          default: ops_admin
        preferred_language:
          type: string
          enum: [zh-CN, en-US, ja-JP]
          default: en-US

    AdminVerifyEmailRequest:
      type: object
      required: [email, verification_code]
      properties:
        email:
          type: string
          format: email
        verification_code:
          type: string
          minLength: 4
          maxLength: 16

    AdminLoginOtpVerifyRequest:
      type: object
      required: [email, role, challenge_id, otp_code]
      properties:
        email:
          type: string
          format: email
        role:
          type: string
          minLength: 2
          maxLength: 64
          default: super_admin
        challenge_id:
          type: string
          minLength: 8
          maxLength: 64
        otp_code:
          type: string
          minLength: 4
          maxLength: 16

    AdminLoginOtpResendRequest:
      type: object
      required: [email, role, challenge_id]
      properties:
        email:
          type: string
          format: email
        role:
          type: string
          minLength: 2
          maxLength: 64
          default: super_admin
        challenge_id:
          type: string
          minLength: 8
          maxLength: 64

    AdminUserStatusUpdateRequest:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [active, suspended, closed]

    ConnectorCatalogUpsertRequest:
      type: object
      required: [connector_id, provider, provider_type]
      properties:
        connector_id:
          type: string
          minLength: 2
          maxLength: 64
        provider:
          type: string
          minLength: 2
          maxLength: 160
        provider_type:
          type: string
          minLength: 2
          maxLength: 64
        asset_classes:
          type: array
          items:
            type: string
        regions:
          type: array
          items:
            type: string
        connectivity:
          type: array
          items:
            type: string
        integration_stage:
          type: string
          enum: [planned, ready, deprecated]
          default: planned

    WaitlistRequest:
      type: object
      required: [work_email, country_region, consent]
      properties:
        work_email:
          type: string
          format: email
        contact_handle:
          type: string
        country_region:
          type: string
        institution_type:
          type: string
        preferred_language:
          type: string
          enum: [zh-CN, en-US, ja-JP]
          default: en-US
        consent:
          type: boolean
        utm_source:
          type: string
        utm_campaign:
          type: string

    WaitlistResponse:
      type: object
      required: [success, data, trace_id]
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          required: [lead_id, message, estimated_contact_time_hours]
          properties:
            lead_id:
              type: string
              example: ld_01JQ9M2ABC
            message:
              type: string
              example: Submitted successfully
            estimated_contact_time_hours:
              type: integer
              example: 24
        trace_id:
          type: string

    StatusResponse:
      type: object
      required: [success, data, trace_id]
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          required: [overall, label, mode, components, updated_at]
          properties:
            overall:
              type: string
              enum: [operational, degraded, outage]
            label:
              type: string
              example: All Systems Operational
            mode:
              type: string
              enum: [non-production, production]
            components:
              type: array
              items:
                type: object
                required: [name, status]
                properties:
                  name:
                    type: string
                  status:
                    type: string
                    enum: [operational, degraded, outage]
            updated_at:
              type: string
              format: date-time
        trace_id:
          type: string

    MarketInstrument:
      type: object
      required: [symbol, venue, asset_class, session, price_precision, qty_precision, status]
      properties:
        symbol:
          type: string
        venue:
          type: string
        asset_class:
          type: string
        session:
          type: string
        price_precision:
          type: integer
        qty_precision:
          type: integer
        status:
          type: string

    MarketsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/MarketInstrument'
            next_page_token:
              type: string
              nullable: true
        trace_id:
          type: string

    Quote:
      type: object
      required: [symbol, venue, last, bid, ask, session_state, ts]
      properties:
        symbol:
          type: string
        venue:
          type: string
        last:
          type: string
        bid:
          type: string
        ask:
          type: string
        bid_size:
          type: string
        ask_size:
          type: string
        change_24h:
          type: string
        session_state:
          type: string
          enum: [open, premarket, postmarket, closed]
        ts:
          type: string
          format: date-time

    QuotesResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            quotes:
              type: array
              items:
                $ref: '#/components/schemas/Quote'
        trace_id:
          type: string

    Bar:
      type: object
      required: [t, o, h, l, c, v]
      properties:
        t:
          type: string
          format: date-time
        o:
          type: string
        h:
          type: string
        l:
          type: string
        c:
          type: string
        v:
          type: string

    BarsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            symbol:
              type: string
            timeframe:
              type: string
            bars:
              type: array
              items:
                $ref: '#/components/schemas/Bar'
        trace_id:
          type: string

    CalendarResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            date:
              type: string
              format: date
            sessions:
              type: array
              items:
                type: object
                properties:
                  venue:
                    type: string
                  asset_class:
                    type: string
                  is_trading_day:
                    type: boolean
                  open_at:
                    type: string
                    format: date-time
                  close_at:
                    type: string
                    format: date-time
                  notes:
                    type: string
        trace_id:
          type: string

    PlaceOrderRequest:
      type: object
      required: [symbol, side, type]
      properties:
        symbol:
          type: string
        venue:
          type: string
        side:
          type: string
          enum: [buy, sell]
        type:
          type: string
          enum: [market, limit, stop]
        quantity:
          type: string
        notional:
          type: string
        price:
          type: string
        stop_price:
          type: string
        time_in_force:
          type: string
          enum: [DAY, GTC, IOC, FOK]
        reduce_only:
          type: boolean
          default: false
        post_only:
          type: boolean
          default: false
        strategy_id:
          type: string
        client_order_id:
          type: string
      oneOf:
        - required: [quantity]
        - required: [notional]

    AmendOrderRequest:
      type: object
      minProperties: 1
      properties:
        price:
          type: string
        quantity:
          type: string
        time_in_force:
          type: string
          enum: [DAY, GTC, IOC, FOK]

    Order:
      type: object
      properties:
        order_id:
          type: string
        client_order_id:
          type: string
        status:
          type: string
        symbol:
          type: string
        side:
          type: string
        type:
          type: string
        quantity:
          type: string
        filled_quantity:
          type: string
        avg_price:
          type: string
          nullable: true
        connector:
          type: string
        created_at:
          type: string
          format: date-time

    OrderResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Order'
        trace_id:
          type: string

    OrderListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Order'
            next_page_token:
              type: string
              nullable: true
        trace_id:
          type: string

    BatchOrderRequest:
      type: object
      required: [orders]
      properties:
        orders:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/PlaceOrderRequest'

    BatchOrderResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            results:
              type: array
              items:
                type: object
                properties:
                  index:
                    type: integer
                  ok:
                    type: boolean
                  order_id:
                    type: string
                  error_code:
                    type: string
        trace_id:
          type: string

    CancelOrderRequest:
      type: object
      properties:
        order_ids:
          type: array
          items:
            type: string
        strategy_id:
          type: string
          nullable: true
        symbol:
          type: string
          nullable: true
      anyOf:
        - required: [order_ids]
        - required: [strategy_id]
        - required: [symbol]

    CancelOrderResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            canceled:
              type: array
              items:
                type: string
            failed:
              type: array
              items:
                type: object
                properties:
                  order_id:
                    type: string
                  error_code:
                    type: string
        trace_id:
          type: string

    Position:
      type: object
      properties:
        symbol:
          type: string
        net_qty:
          type: string
        avg_price:
          type: string
        mark_price:
          type: string
        unrealized_pnl:
          type: string
        realized_pnl:
          type: string
        updated_at:
          type: string
          format: date-time

    PositionsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Position'
        trace_id:
          type: string

    AccountResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            equity:
              type: string
            available_margin:
              type: string
            maintenance_margin:
              type: string
            risk_ratio:
              type: string
            currency:
              type: string
            updated_at:
              type: string
              format: date-time
        trace_id:
          type: string

    AccessBinding:
      type: object
      properties:
        exchange_code:
          type: string
        connector:
          type: string
        binding_status:
          type: string
          enum: [pending, active, failed, suspended]
        activated_at:
          type: string
          format: date-time
          nullable: true

    AccessApplicationCreateRequest:
      type: object
      required: [contact_email, target_markets, target_exchanges]
      properties:
        contact_email:
          type: string
          format: email
        target_markets:
          type: array
          minItems: 1
          items:
            type: string
        target_exchanges:
          type: array
          minItems: 1
          items:
            type: string
        expected_monthly_volume:
          type: string
        preferred_language:
          type: string
          enum: [zh-CN, en-US, ja-JP]
          default: en-US
        notes:
          type: string

    AccessApplication:
      type: object
      properties:
        application_id:
          type: string
        status:
          type: string
          enum: [submitted, reviewing, approved, rejected, provisioning, active]
        review_result:
          type: string
          nullable: true
        provisioning_job_id:
          type: string
          nullable: true
        submitted_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AccessApplicationSubmitResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            application_id:
              type: string
            status:
              type: string
            submitted_at:
              type: string
              format: date-time
        trace_id:
          type: string

    AccessApplicationListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/AccessApplication'
            next_page_token:
              type: string
              nullable: true
        trace_id:
          type: string

    AccessApplicationDetailResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          allOf:
            - $ref: '#/components/schemas/AccessApplication'
            - type: object
              properties:
                bindings:
                  type: array
                  items:
                    $ref: '#/components/schemas/AccessBinding'
        trace_id:
          type: string

    AccessBindingListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/AccessBinding'
        trace_id:
          type: string

    AdminApproveRequest:
      type: object
      properties:
        review_note:
          type: string
        provision_policy:
          type: object
          properties:
            auto_bind:
              type: boolean
            priority_exchanges:
              type: array
              items:
                type: string
            fallback_enabled:
              type: boolean

    AdminRejectRequest:
      type: object
      required: [reject_reason_code]
      properties:
        reject_reason_code:
          type: string
        reject_message:
          type: string

    AdminExchangeCredentialUpsertRequest:
      type: object
      required: [exchange_code, credential_name, api_key_ciphertext, api_secret_ciphertext]
      properties:
        exchange_code:
          type: string
        credential_name:
          type: string
        api_key_ciphertext:
          type: string
        api_secret_ciphertext:
          type: string
        passphrase_ciphertext:
          type: string
          nullable: true
        scope:
          type: object

    ConnectorAvailabilityUpdateRequest:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [up, down]

    AdminActionResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            action:
              type: string
            status:
              type: string
            application_id:
              type: string
              nullable: true
            provisioning_job_id:
              type: string
              nullable: true
        trace_id:
          type: string

    ProvisioningJobResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            job_id:
              type: string
            status:
              type: string
              enum: [queued, running, succeeded, failed, rolled_back]
            current_step:
              type: string
            error_code:
              type: string
              nullable: true
            error_message:
              type: string
              nullable: true
            started_at:
              type: string
              format: date-time
              nullable: true
            finished_at:
              type: string
              format: date-time
              nullable: true
        trace_id:
          type: string

    GenericSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          additionalProperties: true
        trace_id:
          type: string

    Error:
      type: object
      required: [code, message, retryable]
      properties:
        code:
          type: string
        message:
          type: string
        message_i18n_key:
          type: string
          nullable: true
        retryable:
          type: boolean
        upstream_code:
          type: string
          nullable: true
        details:
          type: object
          nullable: true

    ErrorResponse:
      type: object
      required: [success, error, trace_id]
      properties:
        success:
          type: boolean
          enum: [false]
        error:
          $ref: '#/components/schemas/Error'
        trace_id:
          type: string

x-websocket:
  endpoint: wss://stream.pincermarket.com/v1/ws
  auth:
    op: auth
    payload:
      api_key: string
      timestamp: string
      signature: string
  topics:
    - quotes.*
    - trades.*
    - orders.*
    - risk.*
  heartbeat:
    server_ping_interval_sec: 20
    client_pong_timeout_sec: 10