# DO NOT EDIT - This file is automatically generated
# Source repository: git@github.com-emu:crcl-main/match-openapi-internal.git
# Commit: d204251f158a8ff3b6a85158f97a0c8bd770d12f

openapi: 3.1.0
info:
  title: Circle Match API
  description: |
    The Circle Match API provides endpoints for Circle Match, a periodic
    batch-auction venue that coordinates USDC burn demand with USDC mint demand
    for eligible Circle Mint customers.

    ## Authentication

    All REST endpoints require a Bearer token:

    ```
    Authorization: Bearer <API_KEY>
    ```

    ## WebSocket

    Real-time auction state and account events are delivered over a persistent
    WebSocket connection at `wss://api.circle.com/v1/match/ws` (production) or
    `wss://api-sandbox.circle.com/v1/match/ws` (sandbox).

    Obtain a short-lived ticket with `POST /v1/match/ws/ticket`, then pass two
    `Sec-WebSocket-Protocol` values in the upgrade request:

    - `circle-match.v1`
    - `ticket.<jwt>` — the ticket value, prefixed with `ticket.`

    After connection, subscribe to the `market` channel for public auction state
    or the `account` channel for private order and fill events. See the Circle
    Match WebSocket reference for the full protocol specification.

    ## Error codes

    | Code   | HTTP | Description |
    |--------|------|-------------|
    | 136001 | 400  | Auction locked — cancellations and less-competitive fee changes not accepted |
    | 136002 | 400  | Auction settling — try again after settlement completes |
    | 137001 | 400  | Insufficient available balance |
    | 137002 | 400  | Invalid wallet |
    | 137003 | 400  | Wallet not found |
    | 137004 | 409  | Idempotency key reused with different parameters |
    | 137005 | 400  | Fee change not more competitive during lock window |
    | 137006 | 409  | Self-match violation — open order on opposite side of same auction |
    | 137007 | 400  | Invalid fiat account |
    | 137008 | 400  | Maximum orders per auction reached |
    | 137009 | 400  | Transaction limit exceeded |
    | 137010 | 400  | Entity not eligible for Circle Match |
    | 138001 | 400  | Withdrawal amount exceeds available balance |
    | 138002 | 400  | Withdrawal request invalid |
    | 138003 | 404  | No Circle Match account found for this entity |
    | 138004 | 400  | Invalid withdrawal destination |
    | 139001 | 400  | Circle Match wallet invalid |
  version: 1.0.0
servers:
  - url: https://api.circle.com
    description: Production
  - url: https://api-sandbox.circle.com
    description: Sandbox
security:
  - BearerAuth: []
tags:
  - name: Account
    description: Account balance and activity summary
  - name: Orders
    description: Place, list, retrieve, cancel, and modify orders
  - name: Withdrawals
    description: Withdraw restricted mint-side USDC
  - name: WebSocket
    description: Obtain a WebSocket connection ticket
paths:
  /v1/match/account:
    get:
      tags:
        - Account
      operationId: getAccount
      summary: Get account summary
      description: Returns a best-effort snapshot of your Circle Match USDC balance, open-order exposure, and windowed activity totals. Use this for pre-order balance checks and dashboard display. For exact reconciliation, use your order and settlement records instead.
      responses:
        '200':
          description: Account summary
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/AccountSummary'
              example:
                data:
                  accountId: cm_acct_abc123
                  usdc:
                    available:
                      amount: '4000.00'
                      currency: USD
                    reserved:
                      amount: '1000.00'
                      currency: USD
                    total:
                      amount: '5000.00'
                      currency: USD
                  exposure:
                    activeOrderCount: 2
                    mintOrderCount: 0
                    burnOrderCount: 2
                  activity:
                    from: '2026-08-01T00:00:00Z'
                    to: '2026-08-31T23:59:59Z'
                    totalMatched:
                      amount: '18000.00'
                      currency: USD
                    rebatesEarned:
                      amount: '50.00'
                      currency: USD
                    feesPaid:
                      amount: '30.00'
                      currency: USD
        '400':
          description: Circle Match wallet invalid (error 139001)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 139001
                message: Circle Match wallet invalid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No Circle Match account found for this entity (error 138003)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 138003
                message: No Circle Match wallet found
  /v1/match/orders:
    post:
      tags:
        - Orders
      operationId: placeOrder
      summary: Place an order
      description: |-
        Submits a BURN or MINT order to the current auction cycle. Returns 202 Accepted with the orderId and initial `pending` status. The order rests until the auction clears.
        The `idempotencyKey` you supply becomes the `orderId` for all subsequent lookups. Use a unique UUID v4 per order. Reusing a key with different parameters returns error 137004 (HTTP 409).
        BURN orders require `sourceWalletId` and `fiatAccountId`. MINT orders must omit those fields. Use the `orderType` discriminator to select the correct variant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceOrderRequest'
            examples:
              burn_limit:
                summary: BURN limit order
                value:
                  idempotencyKey: 550e8400-e29b-41d4-a716-446655440000
                  orderType: BURN
                  amount:
                    amount: '500.00'
                    currency: USD
                  feeBps: '5'
                  postFillAction: roll
                  sourceWalletId: '1000001234'
                  fiatAccountId: 550e8400-e29b-41d4-a716-446655440001
              mint_limit:
                summary: MINT limit order
                value:
                  idempotencyKey: 661f9511-f30c-52e5-b827-557766551111
                  orderType: MINT
                  amount:
                    amount: '1000.00'
                    currency: USD
                  feeBps: '5'
                  postFillAction: roll
              burn_market:
                summary: BURN market order (no fee ceiling)
                value:
                  idempotencyKey: 772a0622-a41d-63f6-c938-668877662222
                  orderType: BURN
                  amount:
                    amount: '500.00'
                    currency: USD
                  postFillAction: cancel
                  sourceWalletId: '1000001234'
                  fiatAccountId: 550e8400-e29b-41d4-a716-446655440001
      responses:
        '202':
          description: Order accepted and resting in the current auction
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - auctionId
                      - orderId
                      - status
                    properties:
                      auctionId:
                        type: integer
                        description: Auction cycle the order entered
                        example: 42
                      orderId:
                        type: string
                        format: uuid
                        description: Order identifier; equals the idempotencyKey you supplied
                        example: 550e8400-e29b-41d4-a716-446655440000
                      status:
                        type: string
                        enum:
                          - pending
                        example: pending
        '400':
          description: 'Bad request. Error codes: `137001` — insufficient available balance; `137002` — invalid wallet; `137003` — wallet not found; `137007` — invalid fiat account; `137008` — maximum orders per auction reached, wait for the next cycle; `137009` — transaction limit exceeded; `137010` — entity not eligible for Circle Match.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Conflict. Error codes: `137004` — idempotency key reused with different parameters; `137006` — self-match violation, you already have an open order on the opposite side.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
        - Orders
      operationId: listOrders
      summary: List orders
      description: Returns a paginated list of your orders. All query parameters are optional. An unrecognised `status` or `orderType` value returns 400. Passing `from` after `to` returns 400.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number, 1-based
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Results per page (max 100)
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderStatus'
          description: Filter by order status
        - name: orderType
          in: query
          schema:
            $ref: '#/components/schemas/OrderType'
          description: Filter by order type
        - name: orderId
          in: query
          schema:
            type: string
            format: uuid
          description: Return only the order matching this UUID
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          description: Created-at lower bound (inclusive)
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          description: Created-at upper bound (inclusive); must be after `from`
      responses:
        '200':
          description: Paginated order list
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - orders
                      - pagination
                    properties:
                      orders:
                        type: array
                        items:
                          $ref: '#/components/schemas/Order'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '400':
          description: Invalid query parameter value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/match/orders/{id}:
    get:
      tags:
        - Orders
      operationId: getOrder
      summary: Get an order
      description: Returns full detail for a single order, including lineage fields for tracing rolled orders and a fill object that is populated after matching. Follow `lineage.parentOrderId` backward or `lineage.childOrderId` forward to reconstruct the full chain for a rolled order.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The orderId (UUID) to retrieve
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Order detail
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/match/orders/cancel:
    post:
      tags:
        - Orders
      operationId: cancelOrder
      summary: Cancel an order
      description: Cancels a single resting order. Cancellations are blocked during the lock window (error 136001) and while the previous auction is settling (error 136002). If the order has already cleared, it cannot be cancelled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelOrderRequest'
            example:
              auctionId: 42
              orderId: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Order cancelled
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - auctionId
                      - orderId
                      - status
                    properties:
                      auctionId:
                        type: integer
                        example: 42
                      orderId:
                        type: string
                        format: uuid
                        example: 550e8400-e29b-41d4-a716-446655440000
                      status:
                        type: string
                        enum:
                          - cancelled
                        example: cancelled
        '400':
          description: 'Bad request. Error codes: `136001` — auction is locked, cancellations not accepted; `136002` — auction is settling, try again after settlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/match/orders/cancel-all:
    post:
      tags:
        - Orders
      operationId: cancelAllOrders
      summary: Cancel all orders
      description: Cancels every resting order you hold in the current auction cycle. No request body is required. Returns 200 with an empty `orderIds` array if you have no resting orders. Blocked during the lock window (error 136001).
      responses:
        '200':
          description: All orders cancelled
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - auctionId
                      - orderIds
                      - status
                    properties:
                      auctionId:
                        type: integer
                        example: 42
                      orderIds:
                        type: array
                        description: UUIDs of all cancelled orders. Empty if no resting orders existed.
                        items:
                          type: string
                          format: uuid
                        example:
                          - 550e8400-e29b-41d4-a716-446655440000
                          - 661f9511-f30c-52e5-b827-557766551111
                      status:
                        type: string
                        enum:
                          - cancelled
                        example: cancelled
        '400':
          description: 'Bad request. Error codes: `136001` — auction is locked, cancellations not accepted; `136002` — auction is settling, try again after settlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/match/orders/modify:
    post:
      tags:
        - Orders
      operationId: modifyOrder
      summary: Modify an order
      description: |-
        Changes the fee limit on a resting order. Only the fee changes; the order remains in `pending` status with its original size and side.
        Outside the lock window, the fee can move in either direction. During the lock window, the new value must be more competitive than the current value (lower for BURN orders, higher for MINT orders); a less competitive value returns error 137005. Setting `feeBps` to null converts the order to a market order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyOrderRequest'
            example:
              auctionId: 42
              orderId: 550e8400-e29b-41d4-a716-446655440000
              feeBps: '3'
      responses:
        '200':
          description: Order modified
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - auctionId
                      - orderId
                      - status
                    properties:
                      auctionId:
                        type: integer
                        example: 42
                      orderId:
                        type: string
                        format: uuid
                        example: 550e8400-e29b-41d4-a716-446655440000
                      status:
                        type: string
                        enum:
                          - pending
                        example: pending
        '400':
          description: 'Bad request. Error code: `137005` — during the lock window the new fee is less competitive than the current fee.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/match/withdrawals:
    post:
      tags:
        - Withdrawals
      operationId: createWithdrawal
      summary: Withdraw funds
      description: Converts your Circle-Match-only USDC balance to USD and wires it to the specified fiat account. This exit path is for mint-side participants only; burn-side USDC releases automatically when orders fill or are cancelled. No Circle Mint burn fee applies.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
            example:
              idempotencyKey: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
              amount:
                amount: '1000.00'
                currency: USD
              fiatAccountId: 550e8400-e29b-41d4-a716-446655440001
      responses:
        '201':
          description: Withdrawal submitted
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Withdrawal'
              example:
                data:
                  id: 7a2b3c4d-5e6f-7890-abcd-ef1234567890
                  status: pending
        '400':
          description: 'Bad request. Error codes: `137001` — insufficient available balance; `137009` — transaction limit exceeded; `138001` — withdrawal amount exceeds available balance; `138002` — request invalid; `138004` — invalid destination.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No Circle Match account found for this entity (error 138003)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 138003
                message: No Circle Match wallet found
  /v1/match/ws/ticket:
    post:
      tags:
        - WebSocket
      operationId: createWsTicket
      summary: Create a WebSocket ticket
      description: |-
        Issues a short-lived JWT for authenticating a WebSocket connection. The token is validated on signature, issuer, audience, and expiry. Obtain it immediately before opening the socket — it expires at `expiresAt`.
        Connect to the WebSocket endpoint using two `Sec-WebSocket-Protocol` values:
        - `circle-match.v1` — identifies the protocol version - `ticket.<jwt>` — the ticket value from this response, prefixed with `ticket.`
        The server rejects the upgrade with HTTP 401 if the ticket is missing, expired, or has an invalid signature.
      responses:
        '200':
          description: WebSocket ticket issued
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/WsTicket'
              example:
                data:
                  ticket: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                  expiresAt: '2026-09-22T14:05:00Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Money:
      type: object
      description: A monetary amount with its currency
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          description: Decimal amount as a string, rounded to 2 decimal places
          example: '500.00'
        currency:
          type: string
          description: ISO 4217 currency code
          example: USD
    OrderType:
      type: string
      description: Whether this is a BURN (USDC-to-USD) or MINT (USD-to-USDC) order
      enum:
        - BURN
        - MINT
    OrderStatus:
      type: string
      description: |
        Current lifecycle state of the order.
        - `pending`: Accepted and resting in the open auction.
        - `settling`: The auction has cleared; funds are moving.
        - `filled`: Fully matched and settled.
        - `partial_fill`: Partially matched; unfilled remainder handled per `postFillAction`.
        - `unfilled`: No fill received; handled per `postFillAction`.
        - `cancelled`: Cancelled before clearing or dropped by a `cancel` post-fill election.
        - `failed`: Settlement could not be completed.
      enum:
        - pending
        - settling
        - filled
        - partial_fill
        - unfilled
        - cancelled
        - failed
    PostFillAction:
      type: string
      description: |
        Action to take on unfilled remainder after an auction cycle closes.
        - `roll`: Carry remainder into the next auction as a new linked order.
        - `fallback`: Route remainder to standard Circle Mint.
        - `cancel`: Drop the unfilled remainder.
      enum:
        - roll
        - fallback
        - cancel
    OrderLineage:
      type: object
      required:
        - parentOrderId
        - childOrderId
      properties:
        parentOrderId:
          oneOf:
            - type: string
              format: uuid
            - type: 'null'
          description: UUID of the order this rolled from. Null if this is the original order.
          example: null
        childOrderId:
          oneOf:
            - type: string
              format: uuid
            - type: 'null'
          description: UUID of the order this rolled into. Null if not yet rolled or if cancelled.
          example: null
    OrderFill:
      type: object
      required:
        - filledAmount
        - unfilledAmount
        - clearingFeeBps
        - matchedAt
      properties:
        filledAmount:
          $ref: '#/components/schemas/Money'
        unfilledAmount:
          $ref: '#/components/schemas/Money'
        clearingFeeBps:
          type: string
          description: Actual clearing fee applied at settlement, in basis points
          example: '3'
        matchedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the auction cleared
          example: '2026-08-17T00:05:00Z'
    OrderBase:
      type: object
      required:
        - orderId
        - auctionId
        - lineage
        - orderType
        - amount
        - postFillAction
        - status
        - createdAt
        - updatedAt
        - fill
      properties:
        orderId:
          type: string
          format: uuid
          description: Unique order identifier; matches the idempotencyKey from the create request
          example: 550e8400-e29b-41d4-a716-446655440000
        auctionId:
          oneOf:
            - type: integer
            - type: 'null'
          description: Identifier of the auction cycle this order entered. Null before the order is admitted to an auction.
          example: 42
        lineage:
          $ref: '#/components/schemas/OrderLineage'
        orderType:
          $ref: '#/components/schemas/OrderType'
        amount:
          $ref: '#/components/schemas/Money'
        feeBps:
          oneOf:
            - type: string
            - type: 'null'
          description: 'Fee limit in basis points. For BURN orders: maximum fee willing to pay. For MINT orders: minimum rebate required. Null for market orders.'
          example: '5'
        postFillAction:
          $ref: '#/components/schemas/PostFillAction'
        status:
          $ref: '#/components/schemas/OrderStatus'
        createdAt:
          type: string
          format: date-time
          example: '2026-08-17T00:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-08-17T00:05:00Z'
        fill:
          oneOf:
            - $ref: '#/components/schemas/OrderFill'
            - type: 'null'
          description: Fill detail. Null until the order is matched.
    BurnOrder:
      description: A BURN order that redeems USDC for USD
      allOf:
        - $ref: '#/components/schemas/OrderBase'
        - type: object
          required:
            - sourceWalletId
            - fiatAccountId
          properties:
            orderType:
              type: string
              enum:
                - BURN
            sourceWalletId:
              type: string
              description: Circle Mint wallet ID that funded the burn
              example: '1000001234'
            fiatAccountId:
              type: string
              format: uuid
              description: Fiat account that receives settlement proceeds
              example: 550e8400-e29b-41d4-a716-446655440001
    MintOrder:
      description: A MINT order that mints USDC from USD
      allOf:
        - $ref: '#/components/schemas/OrderBase'
        - type: object
          properties:
            orderType:
              type: string
              enum:
                - MINT
            sourceWalletId:
              oneOf:
                - type: string
                - type: 'null'
              description: Always null for MINT orders. Present in the response because the Go server marshals the nil pointer as an explicit null key.
              example: null
            fiatAccountId:
              oneOf:
                - type: string
                - type: 'null'
              description: Always null for MINT orders. Present in the response because the Go server marshals the nil pointer as an explicit null key.
              example: null
    Order:
      description: A Circle Match order — either a BURN (USDC-to-USD) or MINT (USD-to-USDC)
      oneOf:
        - $ref: '#/components/schemas/BurnOrder'
        - $ref: '#/components/schemas/MintOrder'
      discriminator:
        propertyName: orderType
        mapping:
          BURN: '#/components/schemas/BurnOrder'
          MINT: '#/components/schemas/MintOrder'
    ActivityTotals:
      type: object
      required:
        - from
        - to
        - totalMatched
        - rebatesEarned
        - feesPaid
      properties:
        from:
          type: string
          format: date-time
          description: Start of the activity window (inclusive)
          example: '2026-08-01T00:00:00Z'
        to:
          type: string
          format: date-time
          description: End of the activity window (inclusive)
          example: '2026-08-31T23:59:59Z'
        totalMatched:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: Total USD volume matched during the window
        rebatesEarned:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: Gross rebates received (mint-side; non-negative)
        feesPaid:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: Gross fees paid (burn-side; non-negative)
    AccountUsdcBalance:
      type: object
      required:
        - available
        - reserved
        - total
      properties:
        available:
          $ref: '#/components/schemas/Money'
        reserved:
          $ref: '#/components/schemas/Money'
        total:
          $ref: '#/components/schemas/Money'
    AccountExposure:
      type: object
      required:
        - activeOrderCount
        - mintOrderCount
        - burnOrderCount
      properties:
        activeOrderCount:
          type: integer
          description: Total number of currently resting orders across both sides
          example: 3
        mintOrderCount:
          type: integer
          description: Number of currently resting MINT orders
          example: 1
        burnOrderCount:
          type: integer
          description: Number of currently resting BURN orders
          example: 2
    AccountSummary:
      type: object
      required:
        - accountId
        - usdc
        - exposure
        - activity
      properties:
        accountId:
          type: string
          description: Unique Circle Match account identifier
          example: cm_acct_abc123
        usdc:
          $ref: '#/components/schemas/AccountUsdcBalance'
        exposure:
          $ref: '#/components/schemas/AccountExposure'
        activity:
          $ref: '#/components/schemas/ActivityTotals'
    Pagination:
      type: object
      required:
        - page
        - pageSize
        - total
      properties:
        page:
          type: integer
          description: Current page number, 1-based
          example: 1
        pageSize:
          type: integer
          description: Number of results per page
          example: 20
        total:
          type: integer
          description: Total number of matching results across all pages
          example: 142
    PlaceOrderBase:
      type: object
      required:
        - idempotencyKey
        - orderType
        - amount
        - postFillAction
      properties:
        idempotencyKey:
          type: string
          format: uuid
          description: Unique UUID v4 per order. Becomes the orderId for all subsequent lookups. Reusing a key with different parameters returns error 137004.
          example: 550e8400-e29b-41d4-a716-446655440000
        orderType:
          $ref: '#/components/schemas/OrderType'
        amount:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: Amount to burn or mint. Minimum $100, must be a multiple of $100.
        feeBps:
          oneOf:
            - type: string
            - type: 'null'
          description: 'For BURN orders: maximum fee in basis points you are willing to pay. For MINT orders: minimum rebate in basis points you require. Omit or set to null for a market order that matches at any clearing fee.'
          example: '5'
        postFillAction:
          $ref: '#/components/schemas/PostFillAction'
    PlaceBurnOrderRequest:
      description: Request body for placing a BURN order
      allOf:
        - $ref: '#/components/schemas/PlaceOrderBase'
        - type: object
          required:
            - sourceWalletId
            - fiatAccountId
          properties:
            orderType:
              type: string
              enum:
                - BURN
            sourceWalletId:
              type: string
              description: Circle Mint wallet ID that funds the burn
              example: '1000001234'
            fiatAccountId:
              type: string
              format: uuid
              description: Fiat account that receives settlement proceeds
              example: 550e8400-e29b-41d4-a716-446655440001
    PlaceMintOrderRequest:
      description: Request body for placing a MINT order
      allOf:
        - $ref: '#/components/schemas/PlaceOrderBase'
        - type: object
          properties:
            orderType:
              type: string
              enum:
                - MINT
    PlaceOrderRequest:
      description: 'Request body for placing a Circle Match order. Use `orderType` to select the variant: BURN orders require `sourceWalletId` and `fiatAccountId`; MINT orders omit those fields.'
      oneOf:
        - $ref: '#/components/schemas/PlaceBurnOrderRequest'
        - $ref: '#/components/schemas/PlaceMintOrderRequest'
      discriminator:
        propertyName: orderType
        mapping:
          BURN: '#/components/schemas/PlaceBurnOrderRequest'
          MINT: '#/components/schemas/PlaceMintOrderRequest'
    CancelOrderRequest:
      type: object
      required:
        - auctionId
        - orderId
      properties:
        auctionId:
          type: integer
          description: Auction cycle that contains the order to cancel
          example: 42
        orderId:
          type: string
          format: uuid
          description: UUID of the order to cancel
          example: 550e8400-e29b-41d4-a716-446655440000
    ModifyOrderRequest:
      type: object
      required:
        - auctionId
        - orderId
      properties:
        auctionId:
          type: integer
          description: Auction cycle that contains the order to modify
          example: 42
        orderId:
          type: string
          format: uuid
          description: UUID of the order to modify
          example: 550e8400-e29b-41d4-a716-446655440000
        feeBps:
          oneOf:
            - type: string
            - type: 'null'
          description: New fee limit in basis points. During the lock window the new value must be more competitive than the current value (lower for BURN, higher for MINT). Set to null to convert the order to a market order.
          example: '3'
    WithdrawalRequest:
      type: object
      required:
        - idempotencyKey
        - amount
        - fiatAccountId
      properties:
        idempotencyKey:
          type: string
          format: uuid
          description: Unique UUID v4 per withdrawal request
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        amount:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: Amount to withdraw. Must be positive with currency USD.
        fiatAccountId:
          type: string
          format: uuid
          description: Fiat account that receives the USD wire
          example: 550e8400-e29b-41d4-a716-446655440001
    Withdrawal:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for this withdrawal
          example: 7a2b3c4d-5e6f-7890-abcd-ef1234567890
        status:
          type: string
          description: Current status of the withdrawal, passed through from the payout processor.
          example: pending
    WsTicket:
      type: object
      required:
        - ticket
        - expiresAt
      properties:
        ticket:
          type: string
          description: Short-lived JWT for authenticating a WebSocket connection. Validated on signature, issuer, audience, and expiry only — obtain it immediately before opening the socket.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        expiresAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the ticket expires
          example: '2026-09-22T14:05:00Z'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: Circle error code
          example: 137001
        message:
          type: string
          description: Human-readable error description
          example: Insufficient available balance