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

openapi: 3.1.0
info:
  title: StableFX API
  description: |
    The StableFX API provides endpoints for trading stablecoins.

    ## Authentication
    All API requests require authentication using an API key.

    ## Base URL
    The base URL for all API endpoints is: `https://api.circle.com/v1/exchange/stablefx`
  version: 1.0.0
servers:
  - url: https://api.circle.com
    description: StableFX API server
security:
  - BearerAuth: []
tags:
  - name: Quotes
    description: Endpoints for creating and managing quotes
  - name: Trades
    description: Endpoints for creating and managing trades
  - name: Signatures
    description: Endpoints for retrieving presign typed data and registering signatures
  - name: Fees
    description: Endpoints for retrieving fees
  - name: Funding
    description: Endpoints for funding trades
  - name: Webhook Subscriptions
    description: Manage subscriptions to notifications
  - name: Settlement Advance
    description: Request, track, and repay settlement advances.
paths:
  /v1/exchange/stablefx/quotes:
    post:
      security:
        - BearerAuth: []
      operationId: createQuote
      summary: Create a quote
      description: Creates a quote for a trade between two currencies. You should provide an `amount` for the `from` parameter or the `to` parameter, but not for both. Use `type:tradable` for an executable quote or `type:reference` for an indicative quote. Tradable quotes include presign `typedData` for signing.
      tags:
        - Quotes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuote'
      responses:
        '200':
          description: Quote created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQuote-2'
  /v1/exchange/stablefx/trades:
    post:
      security:
        - BearerAuth: []
      operationId: createTrade
      summary: Create a trade
      description: Accepts a quote and creates a trade.
      tags:
        - Trades
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTrade'
      responses:
        '200':
          description: Trade created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trade'
    get:
      security:
        - BearerAuth: []
      operationId: listTrades
      summary: Get all trades
      description: |
        Returns a cursor-paginated list of all trades, newest first by default.

        Pagination is navigated through the `Link` response header, not the response body. Follow the
        `next` relation to walk the collection and stop when it is no longer returned.
      tags:
        - Trades
      parameters:
        - $ref: '#/components/parameters/Status'
        - $ref: '#/components/parameters/Asset'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Ids'
        - $ref: '#/components/parameters/PageSize'
        - in: query
          name: pageAfter
          required: false
          description: |
            Cursor -- returns the trades immediately following the trade with this id in the current
            sort order. With the default `sortOrder=desc` this advances towards older trades.

            Take the value from the `pageAfter` parameter of the `next` link in the `Link` response
            header. Cannot be combined with `pageBefore`.
          schema:
            type: string
            format: uuid
            example: 04a4892d-eef4-4df9-a5a4-4ccfc43497d6
        - in: query
          name: pageBefore
          required: false
          description: |
            Cursor -- returns the trades immediately preceding the trade with this id in the current
            sort order. With the default `sortOrder=desc` this navigates back towards newer trades.

            Take the value from the `pageBefore` parameter of the `prev` link in the `Link` response
            header. Cannot be combined with `pageAfter`.
          schema:
            type: string
            format: uuid
            example: 04a4892d-eef4-4df9-a5a4-4ccfc43497d6
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - in: query
          name: type
          required: true
          description: The type of trade.
          schema:
            $ref: '#/components/schemas/Type'
        - in: query
          name: settlementTransactionHash
          required: false
          description: Filter trades by settlement transaction hash.
          schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{64}$
            example: '0xf97c6a87511583d5c7e8e72f8e1fe38bfd24350edda78fddbe67125f3cf0a122'
        - in: query
          name: sortOrder
          required: false
          description: Sort order for trades by creation date. Defaults to `desc` (newest first).
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Trade retrieved successfully
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Trade'
  /v1/exchange/stablefx/trades/{tradeId}:
    get:
      security:
        - BearerAuth: []
      operationId: getTradeById
      summary: Get a trade
      description: Returns a trade specified by the ID path parameter
      tags:
        - Trades
      parameters:
        - in: path
          name: tradeId
          required: true
          description: The ID of the trade.
          schema:
            $ref: '#/components/schemas/Id'
        - in: query
          name: type
          required: true
          description: The type of trader.
          schema:
            $ref: '#/components/schemas/Type'
      responses:
        '200':
          description: Trade retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeDetail'
  /v1/exchange/stablefx/signatures:
    post:
      security:
        - BearerAuth: []
      operationId: registerTradeSignature
      summary: Register a trade signature
      description: Registers a signed EIP-712 payload from the trader that confirms trade intent.
      tags:
        - Signatures
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterTradeSignatureRequest'
      responses:
        '200':
          description: Trade signature registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterTradeSignatureResponse'
  /v1/exchange/stablefx/fees/{tradeId}:
    get:
      security:
        - BearerAuth: []
      operationId: getTradeFee
      summary: Get fee for a trade
      description: Returns the fee associated with the trade ID provided in the path parameter.
      tags:
        - Fees
      parameters:
        - in: path
          name: tradeId
          required: true
          description: The ID of the trade.
          schema:
            $ref: '#/components/schemas/Id'
      responses:
        '200':
          description: Fee retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
  /v1/exchange/stablefx/signatures/presign/{tradeId}:
    get:
      security:
        - BearerAuth: []
      operationId: generateTradeSignatureData
      summary: Generate trade presign data
      description: Returns the EIP-712 Permit2 payload that the maker must sign for a trade.
      tags:
        - Signatures
      parameters:
        - in: path
          name: tradeId
          required: true
          description: The ID of the trade.
          schema:
            $ref: '#/components/schemas/Id'
        - in: query
          name: recipientAddress
          required: true
          description: The address of the recipient of the settlement tokens.
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
      responses:
        '200':
          description: Signature data generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradePresignData'
  /v1/exchange/stablefx/signatures/funding/presign:
    post:
      security:
        - BearerAuth: []
      operationId: generateFundingPresignData
      summary: Generate funding presign data
      description: |
        Returns the Permit2 EIP-712 payload that the trader must sign for funding operations. `fundingMode` net option is supported for maker funding requests.

        When `fundingMode` is `delegate`, the response instead contains two typed-data payloads: one for the trader to sign (a zero-amount authorization) and one for the funder to sign (carrying the actual delivery amount). Delegate mode supports both maker and taker, requires `funderAddress` and `recipientAddress`, and accepts exactly one contract trade ID per request.
      tags:
        - Signatures
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundingPresign'
      responses:
        '200':
          description: Funding presign data generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingPresign-2'
  /v1/exchange/stablefx/fund:
    post:
      security:
        - BearerAuth: []
      operationId: fundTrade
      summary: Fund trades
      description: |
        Executes funding for trades using Permit2 signatures. This endpoint relays the signed permit data to complete the funding operation for trades.

        When `fundingMode` is `delegate`, the request must include the trader's delegate-funding authorization in `permit2`/`signature` along with the funder's permit in `funderPermit2`/`funderSignature`. The funder delivers the tokens on the trader's behalf; no tokens transfer from the trader.
      tags:
        - Funding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fund'
      responses:
        '200':
          description: Funding completed successfully
        '400':
          description: Bad request - validation error
  /v2/stablefx/notifications/subscriptions:
    post:
      tags:
        - Webhook Subscriptions
      summary: Create a webhook subscription
      description: |
        Create a webhook subscription by configuring an endpoint to receive notifications.
      operationId: createSubscription
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/XRequestId'
      requestBody:
        $ref: '#/components/requestBodies/CreateSubscription'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubscription'
          description: Successfully created webhook subscription
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
    get:
      security:
        - BearerAuth: []
      operationId: getSubscriptions
      summary: Get all webhook subscriptions
      description: Returns an array of all webhook subscriptions.
      tags:
        - Webhook Subscriptions
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriptions'
          description: Successfully retrieved webhook subscriptions
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/NotAuthorized'
  /v2/stablefx/notifications/subscriptions/{id}:
    get:
      tags:
        - Webhook Subscriptions
      summary: Get a notification subscription
      description: Returns an existing notification subscription.
      operationId: getSubscription
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Id-2'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription-2'
          description: Successfully retrieved webhook subscription
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - Webhook Subscriptions
      summary: Update a notification subscription
      description: |
        Update a notification subscription by configuring an endpoint to receive notifications.
      operationId: updateSubscription
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Id-2'
        - $ref: '#/components/parameters/XRequestId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateSubscription'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription-2'
          description: Successfully updated webhook subscription
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Webhook Subscriptions
      summary: Delete a notification subscription
      description: Delete an existing subscription.
      operationId: deleteSubscription
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Id-2'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '204':
          description: |
            Successfully deleted webhook subscription.

            Note: response body is returned empty.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/stablefx/notifications/publicKey/{id}:
    get:
      tags:
        - Webhook Subscriptions
      summary: Get a notification signature public key
      description: |
        Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

        In the headers of each webhook, you can find

          - `X-Circle-Signature`: a header containing the digital signature generated by Circle.

          - `X-Circle-Key-Id`: a header containing the UUID. This is will be used as the `ID` as URL parameter to retrieve the relevant public key.
      operationId: getNotificationSignature
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Id-2'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: Successfully retrieved a digital notification signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSignaturePublicKey'
        '400':
          $ref: '#/components/responses/DefaultError'
  /v1/exchange/stablefx/settlementAdvances/credit:
    get:
      security:
        - BearerAuth: []
      operationId: getSettlementAdvanceCredit
      summary: Get settlement advance credit line
      description: |
        Returns the maker's settlement-advance credit line including total limit,
        current usage, available headroom per currency, and the applicable fee
        schedule (recurring, draw, and reservation fees).
      tags:
        - Settlement Advance
      responses:
        '200':
          description: Credit line view.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceCredit'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credit line not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/reserve:
    post:
      security:
        - BearerAuth: []
      operationId: reserveSettlementAdvance
      summary: Reserve settlement advance credit
      description: |
        Holds credit so the maker can lock in a fee snapshot before requesting
        the settlement advance. Reservations expire after a short window (~15
        minutes); after expiry the maker must reserve again.

        Replaying the same `idempotencyKey` returns the existing reservation.
        Submitting a different `idempotencyKey` while another reservation for
        the same currency is still active will be rejected — the maker must
        cancel the active reservation first before creating a new one. There
        is one active reservation allowed per currency.

        A reservation is automatically cancelled after a single settlement advance
        is made against it.

        Calling `/reserve` is optional; the maker may skip it and go straight
        to requesting the settlement advance.
      tags:
        - Settlement Advance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReserveSettlementAdvance'
      responses:
        '200':
          description: Reservation created or existing reservation returned on idempotent replay.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceReservation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credit line not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An active reservation for the same currency already exists. Cancel the existing reservation before creating a new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/reservations:
    get:
      security:
        - BearerAuth: []
      operationId: listSettlementAdvanceReservations
      summary: List settlement advance reservations
      description: |
        Returns the maker's settlement advance reservations, optionally filtered
        by status and currency. Supports cursor-based pagination, newest first.
      tags:
        - Settlement Advance
      parameters:
        - in: query
          name: status
          required: false
          schema:
            $ref: '#/components/schemas/ReservationStatus'
          description: Filter by reservation status. Omit to return reservations in any status.
        - in: query
          name: currency
          required: false
          schema:
            type: string
            example: USDC
          description: Filter by reservation currency.
        - in: query
          name: pageBefore
          required: false
          schema:
            type: string
            format: uuid
          description: Cursor -- return reservations strictly before this id.
        - in: query
          name: pageAfter
          required: false
          schema:
            type: string
            format: uuid
          description: Cursor -- return reservations strictly after this id.
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: List of settlement advance reservations.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceReservations'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/reservations/{reservationId}:
    get:
      security:
        - BearerAuth: []
      operationId: getSettlementAdvanceReservation
      summary: Get a settlement advance reservation
      description: |
        Returns a single settlement advance reservation by ID.
      tags:
        - Settlement Advance
      parameters:
        - name: reservationId
          in: path
          required: true
          description: The reservation identifier.
          schema:
            $ref: '#/components/schemas/Id'
      responses:
        '200':
          description: Settlement advance reservation.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceReservation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Reservation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/reservations/{reservationId}/cancel:
    post:
      security:
        - BearerAuth: []
      operationId: cancelSettlementAdvanceReservation
      summary: Cancel a settlement advance reservation
      description: |
        Cancels an active settlement advance reservation, releasing the held
        credit back to the line. Only reservations in `active` status
        can be canceled.
      tags:
        - Settlement Advance
      parameters:
        - name: reservationId
          in: path
          required: true
          description: The reservation identifier.
          schema:
            $ref: '#/components/schemas/Id'
      responses:
        '200':
          description: Reservation canceled successfully.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceReservation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Reservation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/signatures/settlementAdvances/presign:
    post:
      security:
        - BearerAuth: []
      operationId: presignSettlementAdvance
      summary: Get settlement advance Permit2 typed data for signing
      description: |
        Returns Permit2 typed-data the maker signs to authorize delegate funding
        of their side of a trade. The witness is a `DelegateFundingAuthorization`
        with `permitted.amount = 0` -- Permit2 is used purely as an authorization
        carrier, no tokens transfer from the maker.

        Stateless: no persistence, no side effects.
      tags:
        - Signatures
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresignSettlementAdvance'
      responses:
        '200':
          description: Typed-data ready for the maker to sign.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvancePresign'
        '400':
          description: Invalid request or trade state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trade not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances:
    post:
      security:
        - BearerAuth: []
      operationId: requestSettlementAdvance
      summary: Request a settlement advance
      description: |
        Submit the Permit2 signature generated from the presign endpoint along with
        the witness payload. Funding runs asynchronously after this call returns.

        Idempotent on `tradeId`: replays for the same trade either return the
        in-progress settlement advance or short-circuit when the trade already
        has a non-failed active settlement advance.

        Calling `/reserve` first is optional. The request body is the same
        whether or not a prior reservation exists.

        **Collateral rounding**: when the repayment is complete and collateral is
        released, Circle rounds the collateral amount to 2 decimal places.
      tags:
        - Settlement Advance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptSettlementAdvance'
      responses:
        '200':
          description: Settlement advance requested; funding in progress.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceAccepted'
        '400':
          description: |
            Invalid request, signature mismatch, duplicate settlement advance, or credit limit exceeded.

            Relevant error codes:
            - `301031` (`INSUFFICIENT_CREDIT_LINE_FUNDS`) — the requested advance amount exceeds one of
              two limits enforced at creation time:
              1. **USD headroom**: the USD-equivalent of the advance exceeds the credit line's remaining USD balance.
              2. **Available-in-currency**: the advance amount (in the requested currency) exceeds the
                 per-currency pool available for that stablecoin. Check the `availableInCurrencies` field
                 on the credit line before requesting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trade or credit line not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            The quoted exchange rate diverges from the live reference rate by more than the
            configured risk margin.

            Relevant error codes:
            - `301098` (`STABLE_FX_QUOTE_PRICE_DIVERGENCE`) — quote rate is outside the acceptable
              spread from the current TER fiat reference rate. Submit a fresh quote and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: |
            Settlement advance creation rate limit exceeded. The credit line has had too many
            advances created within the configured time window.

            Relevant error codes:
            - `301099` (`SETTLEMENT_ADVANCE_RATE_LIMITED`) — wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      security:
        - BearerAuth: []
      operationId: listSettlementAdvances
      summary: List settlement advances
      description: |
        Returns the maker's settlement advances with their lifecycle status,
        filterable by status and date range. Supports cursor-based pagination.
      tags:
        - Settlement Advance
      parameters:
        - in: query
          name: status
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AdvanceCreditStatus'
          description: Filter by advance credit status. Omit to return advances in any status.
        - in: query
          name: startCreateDateInclusive
          required: false
          schema:
            type: string
            format: date-time
          description: Start of the creation date range (inclusive).
        - in: query
          name: endCreateDateInclusive
          required: false
          schema:
            type: string
            format: date-time
          description: End of the creation date range (inclusive).
        - in: query
          name: pageBefore
          required: false
          schema:
            type: string
            format: uuid
          description: Cursor -- return advances strictly before this id.
        - in: query
          name: pageAfter
          required: false
          schema:
            type: string
            format: uuid
          description: Cursor -- return advances strictly after this id.
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: List of settlement advances.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceHistory'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/{advanceId}:
    get:
      security:
        - BearerAuth: []
      operationId: getSettlementAdvanceDetail
      summary: Get settlement advance detail
      description: |
        Returns the full detail of a single settlement advance including its
        lifecycle status, advance and collateral amounts, fee information,
        and any repayments applied.
      tags:
        - Settlement Advance
      parameters:
        - name: advanceId
          in: path
          required: true
          description: The settlement advance identifier.
          schema:
            $ref: '#/components/schemas/Id'
      responses:
        '200':
          description: Settlement advance detail.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceDetail'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Settlement advance not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/repayments:
    post:
      security:
        - BearerAuth: []
      operationId: repaySettlementAdvance
      summary: Repay a settlement advance
      description: |
        Records a repayment against the credit line backing a settlement advance.
        Any excess would be balance of the Circle Mint account.

        **Rounding**: for USDC and EURC repayments, the amount should be rounded
        up to 2 decimal places. Other stablecoins (e.g. MXNB, QCAD, AUDF, ZARU)
        are not subject to rounding.

        Idempotent on `idempotencyKey`: replays with the same key and same
        amount are no-ops.
      tags:
        - Settlement Advance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepaySettlementAdvance'
      responses:
        '201':
          description: Repayment recorded successfully.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceRepayment'
        '400':
          description: Invalid request or repayment rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credit line not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Idempotency key reused with different request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/exchange/stablefx/settlementAdvances/repayments/{repaymentId}:
    get:
      security:
        - BearerAuth: []
      operationId: getSettlementAdvanceRepayment
      summary: Get a settlement advance repayment
      description: |
        Returns the details of a specific settlement advance repayment.
      tags:
        - Settlement Advance
      parameters:
        - name: repaymentId
          in: path
          required: true
          description: The repayment identifier.
          schema:
            $ref: '#/components/schemas/Id'
      responses:
        '200':
          description: Repayment details.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementAdvanceRepayment'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Repayment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
webhooks:
  tradeConfirmed:
    post:
      summary: Trade confirmed
      description: The StableFX trade has been confirmed by the exchange.
      operationId: tradeConfirmed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.confirmed
      responses:
        '200':
          description: Webhook received successfully
  tradePendingSettlement:
    post:
      summary: Trade pending settlement
      description: The StableFX trade has been confirmed onchain and is awaiting funding from taker and maker.
      operationId: tradePendingSettlement
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.pendingSettlement
      responses:
        '200':
          description: Webhook received successfully
  tradeMakerFunded:
    post:
      summary: Trade maker funded
      description: The maker has funded their side of the trade. The maker's fund delivery transaction has been confirmed onchain.
      operationId: tradeMakerFunded
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.makerFunded
      responses:
        '200':
          description: Webhook received successfully
  tradeTakerFunded:
    post:
      summary: Trade taker funded
      description: The taker has funded their side of the trade. The taker's fund delivery transaction has been confirmed onchain.
      operationId: tradeTakerFunded
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.takerFunded
      responses:
        '200':
          description: Webhook received successfully
  tradeCompleted:
    post:
      summary: Trade completed
      description: The StableFX trade has been completed successfully. Both the maker and the taker have funded their side and the trade is fully settled.
      operationId: tradeCompleted
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.completed
      responses:
        '200':
          description: Webhook received successfully
  tradeRefunded:
    post:
      summary: Trade refunded
      description: The StableFX trade has been refunded.
      operationId: tradeRefunded
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.refunded
      responses:
        '200':
          description: Webhook received successfully
  tradeFailed:
    post:
      summary: Trade failed
      description: The StableFX trade has failed.
      operationId: tradeFailed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.failed
      responses:
        '200':
          description: Webhook received successfully
  tradeBreached:
    post:
      summary: Trade breached
      description: The StableFX trade has breached its maturity date.
      operationId: tradeBreached
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.breached
      responses:
        '200':
          description: Webhook received successfully
  contractRecordTradeFailed:
    post:
      summary: Record trade operation failed
      description: The record trade operation on the contract has failed. The initial onchain recording of the trade was unsuccessful.
      operationId: contractRecordTradeFailed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.contract.recordTrade.failed
      responses:
        '200':
          description: Webhook received successfully
  contractMakerDeliverFailed:
    post:
      summary: Maker deliver operation failed
      description: The maker deliver operation on the contract has failed. The maker's deliver transaction failed to confirm onchain.
      operationId: contractMakerDeliverFailed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.contract.makerDeliver.failed
      responses:
        '200':
          description: Webhook received successfully
  contractTakerDeliverFailed:
    post:
      summary: Taker deliver operation failed
      description: The taker deliver operation on the contract has failed. The taker's deliver transaction failed to confirm onchain.
      operationId: contractTakerDeliverFailed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.contract.takerDeliver.failed
      responses:
        '200':
          description: Webhook received successfully
  tradeMakerDelegateFunded:
    post:
      summary: Trade maker delegate funded
      description: The maker leg has been funded via a delegated funder. Distinct from makerFunded so subscribers can tell direct-funded legs apart from delegate-funded legs.
      operationId: tradeMakerDelegateFunded
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.makerDelegateFunded
      responses:
        '200':
          description: Webhook received successfully
  tradeTakerDelegateFunded:
    post:
      summary: Trade taker delegate funded
      description: The taker leg has been funded via a delegated funder. Distinct from takerFunded so subscribers can tell direct-funded legs apart from delegate-funded legs.
      operationId: tradeTakerDelegateFunded
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.trade.takerDelegateFunded
      responses:
        '200':
          description: Webhook received successfully
  contractMakerDelegateDeliverFailed:
    post:
      summary: Contract maker delegate deliver failed
      description: The maker's delegated funding transaction failed on-chain.
      operationId: contractMakerDelegateDeliverFailed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.contract.makerDelegateDeliver.failed
      responses:
        '200':
          description: Webhook received successfully
  contractTakerDelegateDeliverFailed:
    post:
      summary: Contract taker delegate deliver failed
      description: The taker's delegated funding transaction failed on-chain.
      operationId: contractTakerDelegateDeliverFailed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    notificationType:
                      type: string
                      enum:
                        - stablefx.contract.takerDelegateDeliver.failed
      responses:
        '200':
          description: Webhook received successfully
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: PREFIX:ID:SECRET
      description: Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.
  schemas:
    Currency:
      type: string
      description: Currency code
      enum:
        - USDC
        - EURC
    Amount:
      type: string
      pattern: ^\d+(?:\.\d{1,6})?$
      description: Amount of currency, formatted as a string with up to six decimal places.
      example: '100.00'
    CurrencyAmount:
      type: object
      description: Currency and amount details for a foreign exchange transaction
      required:
        - currency
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        amount:
          $ref: '#/components/schemas/Amount'
    Tenor:
      type: string
      description: The settlement schedule for the trade
      enum:
        - instant
        - hourly
        - daily
    QuoteType:
      type: string
      description: The quote type. Use tradable for executable quotes or reference for indicative quotes.
      enum:
        - reference
        - tradable
      default: tradable
    BlockchainAddress:
      type: string
      description: A blockchain address
      example: '0x1234567890abcdef1234567890abcdef12345678'
    CreateQuote:
      type: object
      description: Request body for creating an exchange quote
      required:
        - from
        - to
        - tenor
      properties:
        from:
          $ref: '#/components/schemas/CurrencyAmount'
        to:
          $ref: '#/components/schemas/CurrencyAmount'
        tenor:
          $ref: '#/components/schemas/Tenor'
        type:
          $ref: '#/components/schemas/QuoteType'
        recipientAddress:
          description: The address that should receive taker proceeds. Required for tradable quote requests.
          $ref: '#/components/schemas/BlockchainAddress'
    Id:
      type: string
      format: uuid
      description: System-generated unique identifier of the resource.
      example: c4d1da72-111e-4d52-bdbf-2e74a2d803d5
    Rate:
      type: number
      format: double
      description: Exchange rate for the quote
      example: 0.915
    CreateDate:
      type: string
      format: date-time
      description: Date and time when the resource was created
      example: '2023-01-01T12:04:05Z'
    ExpireDate:
      type: string
      format: date-time
      description: Date and time when the resource expires
      example: '2023-01-01T12:04:05Z'
    Permit2EIP712Domain:
      type: object
      description: Permit2 EIP-712 domain separator
      required:
        - name
        - chainId
        - verifyingContract
      properties:
        name:
          type: string
          description: The name of the signing domain
          example: Permit2
        chainId:
          type: integer
          description: The chain ID of the network
          example: 11155111
        verifyingContract:
          type: string
          description: The address of the verifying contract
          example: '0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE'
    TradeSignatureConsideration:
      type: object
      description: EIP-712 typed data for a StableFX trade created from a quote.
      properties:
        quoteId:
          type: string
        base:
          type: string
        quote:
          type: string
        baseAmount:
          type: string
        quoteAmount:
          type: string
        maturity:
          type: string
          format: epoch
          description: The settlement maturity timestamp for the trade, as a string representation of a uint256
          example: '1716153600'
    TradePermit2Message:
      type: object
      description: The Permit2 message for trade registration
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          type: object
          description: Token permission details
          required:
            - token
            - amount
          properties:
            token:
              type: string
              description: The address of the token to be funded
              example: '0x3600000000000000000000000000000000000000'
            amount:
              type: string
              description: The prefunded risk buffer amount of tokens to be funded, as a string representation of a uint256
              example: '429000000'
        spender:
          type: string
          description: The address of the StableFX contract
          example: '0xa8f94168b4981840ba27d423f4ad6332bedee006'
        nonce:
          type: string
          description: A unique nonce for the signature to prevent replay attacks, as a string representation of a uint256
          example: '309585810'
        deadline:
          type: string
          format: epoch
          description: The validity period for the signature in epoch seconds, as a string representation of a uint256
          example: '1770302983'
        witness:
          type: object
          description: Witness data containing trade details
          required:
            - consideration
            - fee
            - authorizer
          properties:
            consideration:
              $ref: '#/components/schemas/TradeSignatureConsideration'
            recipient:
              type:
                - string
                - 'null'
              description: The address of the recipient of the trade. Only included in taker trades, null for maker trades.
              example: '0x1f531ce3c418bbd830d06138a9e5b5eacfdfb3d6'
            fee:
              type: string
              description: The fee for the trade, as a string representation of a uint256
              example: '80000'
            authorizer:
              type: string
              description: The authorizer is the address of the entity that authorizes the trade. For StableFX this does not need to be set and defaults to the zero-address sentinel.
              example: '0x0000000000000000000000000000000000000000'
    TradeTypedData:
      type: object
      description: EIP-712 typed data for trade registration
      required:
        - domain
        - types
        - primaryType
        - message
      properties:
        domain:
          $ref: '#/components/schemas/Permit2EIP712Domain'
        types:
          type: object
          description: EIP-712 types definition
          required:
            - EIP712Domain
            - Consideration
          properties:
            EIP712Domain:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  type:
                    type: string
            Consideration:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  type:
                    type: string
            TraderDetails:
              type: array
              description: Type definition for trader (maker or taker) trades. Replaces the legacy TakerDetails and MakerDetails type definitions and adds the `authorizer` field.
              items:
                type: object
                properties:
                  name:
                    type: string
                  type:
                    type: string
              example:
                - name: consideration
                  type: Consideration
                - name: recipient
                  type: address
                - name: fee
                  type: uint256
                - name: authorizer
                  type: address
            TokenPermissions:
              type: array
              description: Type definition for token permissions
              items:
                type: object
                properties:
                  name:
                    type: string
                  type:
                    type: string
            PermitWitnessTransferFrom:
              type: array
              description: Type definition for permit witness transfer
              items:
                type: object
                properties:
                  name:
                    type: string
                  type:
                    type: string
        primaryType:
          type: string
          description: The primary type for the EIP-712 data to be signed
          enum:
            - PermitWitnessTransferFrom
          example: PermitWitnessTransferFrom
        message:
          $ref: '#/components/schemas/TradePermit2Message'
    CreateQuote-2:
      type: object
      description: Quote for an FX transaction
      properties:
        id:
          $ref: '#/components/schemas/Id'
        rate:
          $ref: '#/components/schemas/Rate'
        to:
          $ref: '#/components/schemas/CurrencyAmount'
        from:
          $ref: '#/components/schemas/CurrencyAmount'
        createdAt:
          $ref: '#/components/schemas/CreateDate'
        expiresAt:
          $ref: '#/components/schemas/ExpireDate'
        fee:
          description: The fee for the transaction, denominated in the 'to' currency.
          $ref: '#/components/schemas/Amount'
        collateral:
          description: Optional collateral amount required for the quote, denominated in the 'from' currency.
          $ref: '#/components/schemas/Amount'
        typedData:
          description: Permit2 EIP-712 typed data for signing before trade creation.
          $ref: '#/components/schemas/TradeTypedData'
    TradeStatus:
      type: string
      enum:
        - pending
        - complete
        - confirmed
        - pending_settlement
        - taker_funded
        - maker_funded
        - refunded
        - breaching
        - breached
    Type:
      type: string
      description: The type of trader.
      enum:
        - maker
        - taker
    ContractTradeId:
      type: string
      description: The ID of the trade on the contract.
      pattern: ^[0-9]+$
      example: '24'
    UpdateDate:
      type: string
      format: date-time
      description: Date and time when the resource was last updated
      example: '2023-01-01T12:04:05Z'
    SettlementTransactionHash:
      type:
        - string
        - 'null'
      description: The hash of the settlement transaction on-chain.
      pattern: ^0x[a-fA-F0-9]{64}$
      example: '0xf97c6a87511583d5c7e8e72f8e1fe38bfd24350edda78fddbe67125f3cf0a122'
    Maturity:
      type:
        - string
        - 'null'
      format: date-time
      description: The date when the trade has matured.
      example: '2023-01-01T12:04:05Z'
    CompleteDate:
      type:
        - string
        - 'null'
      format: date-time
      description: The time/date the trade was completed.
      example: '2023-01-01T12:04:05Z'
    Trade:
      type: object
      description: A StableFX trade created from a quote.
      properties:
        id:
          $ref: '#/components/schemas/Id'
        contractTradeId:
          $ref: '#/components/schemas/ContractTradeId'
        status:
          $ref: '#/components/schemas/TradeStatus'
        rate:
          $ref: '#/components/schemas/Rate'
        from:
          $ref: '#/components/schemas/CurrencyAmount'
        to:
          $ref: '#/components/schemas/CurrencyAmount'
        fee:
          description: Trade fee charged to the requesting party (matching the `type` parameter — taker or maker), denominated in the `to` currency.
          $ref: '#/components/schemas/Amount'
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
        quoteId:
          $ref: '#/components/schemas/Id'
        settlementTransactionHash:
          $ref: '#/components/schemas/SettlementTransactionHash'
        maturity:
          $ref: '#/components/schemas/Maturity'
        tenor:
          $ref: '#/components/schemas/Tenor'
        completeDate:
          $ref: '#/components/schemas/CompleteDate'
        providerTradeId:
          type:
            - string
            - 'null'
          description: The liquidity provider's own trade identifier. Populated for makers once the LP has confirmed the trade; absent for takers.
    IdempotencyKey:
      type: string
      description: Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. To create a UUIDv4 go to [uuidgenerator.net](https://www.uuidgenerator.net). If the same key is reused, it will be treated as the same request and the original response will be returned.
      example: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
      format: uuid
    TokenPermissions:
      type: object
      description: Token permissions for Permit2
      required:
        - token
        - amount
      properties:
        token:
          type: string
          description: The token contract address
          example: 0xTOKEN
        amount:
          type: string
          description: The amount of tokens permitted, as a string representation of a uint256.
          example: '1000'
    TakerPermit2Message:
      type: object
      description: The taker Permit2 message for trade creation. Contains the signed Permit2 witness transfer data including taker-specific witness details with consideration, recipient, and fee.
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          $ref: '#/components/schemas/TokenPermissions'
        spender:
          type: string
          description: The address of the StableFX contract
          example: '0xa8f94168b4981840ba27d423f4ad6332bedee006'
        nonce:
          type: string
          description: A unique nonce for the signature to prevent replay attacks, as a string representation of a uint256
          example: '309585810'
        deadline:
          type: string
          format: epoch
          description: The validity period for the signature in epoch seconds, as a string representation of a uint256
          example: '1770302983'
        witness:
          type: object
          description: Witness data containing taker trade details
          required:
            - consideration
            - recipient
            - fee
          properties:
            consideration:
              $ref: '#/components/schemas/TradeSignatureConsideration'
            recipient:
              type: string
              description: The address of the recipient of the trade
              example: '0x1f531ce3c418bbd830d06138a9e5b5eacfdfb3d6'
            fee:
              type: string
              description: The fee for the trade, as a string representation of a uint256
              example: '80000'
    CreateTrade:
      type: object
      description: Request body for creating a trade. Accepts a quote and submits a signed taker Permit2 message to create the trade. The taker signs the `typedData` payload returned by the presign endpoint and includes the signed message, signature, and signer address.
      required:
        - idempotencyKey
        - quoteId
        - address
        - message
        - signature
      properties:
        idempotencyKey:
          $ref: '#/components/schemas/IdempotencyKey'
        quoteId:
          $ref: '#/components/schemas/Id'
        address:
          description: The wallet address signing the trade presign data.
          $ref: '#/components/schemas/BlockchainAddress'
        message:
          description: The taker Permit2 message derived from the quote response typedData.message.
          $ref: '#/components/schemas/TakerPermit2Message'
        signature:
          type: string
          description: The signature generated from signing the trade presign data.
    SignerAddress:
      type:
        - string
        - 'null'
      description: The wallet address of the signer.
      example: '0xf0e7ccf7817b30fa0dd6bdeaea3ad54c140647b2'
    ContractTransaction:
      type: object
      description: A blockchain transaction associated with a trade
      properties:
        status:
          type: string
          description: The status of the transaction
          enum:
            - pending
            - success
            - failed
          example: success
        txHash:
          type: string
          description: The transaction hash on the blockchain
          example: '0x522a01ed8750423ab213a3d4618f231e0984874509521e98977f017b452cd455'
        errorDetails:
          type:
            - string
            - 'null'
          description: Error details if the transaction failed
    ContractTransactions:
      type: object
      description: Collection of contract functions associated with a trade
      properties:
        recordTrade:
          $ref: '#/components/schemas/ContractTransaction'
        takerDeliver:
          $ref: '#/components/schemas/ContractTransaction'
        makerDeliver:
          $ref: '#/components/schemas/ContractTransaction'
        breach:
          description: Only present for breached trades.
          $ref: '#/components/schemas/ContractTransaction'
    TradeDetail:
      type: object
      description: Detailed trade information including contract transactions
      properties:
        id:
          $ref: '#/components/schemas/Id'
        contractTradeId:
          $ref: '#/components/schemas/ContractTradeId'
        status:
          $ref: '#/components/schemas/TradeStatus'
        rate:
          $ref: '#/components/schemas/Rate'
        from:
          $ref: '#/components/schemas/CurrencyAmount'
        to:
          $ref: '#/components/schemas/CurrencyAmount'
        fee:
          description: Trade fee charged to the requesting party (matching the `type` parameter — taker or maker), denominated in the `to` currency.
          $ref: '#/components/schemas/Amount'
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
        quoteId:
          $ref: '#/components/schemas/Id'
        collateral:
          description: Collateral amount required for the trade, denominated in the `from` currency.
          $ref: '#/components/schemas/Amount'
        settlementTransactionHash:
          $ref: '#/components/schemas/SettlementTransactionHash'
        maturity:
          $ref: '#/components/schemas/Maturity'
        tenor:
          $ref: '#/components/schemas/Tenor'
        completeDate:
          $ref: '#/components/schemas/CompleteDate'
        signerAddress:
          $ref: '#/components/schemas/SignerAddress'
        contractTransactions:
          $ref: '#/components/schemas/ContractTransactions'
        providerTradeId:
          type:
            - string
            - 'null'
          description: The liquidity provider's own trade identifier (e.g. Talos MarketTradeID). Populated for makers on Talos-backed trades once the LP has confirmed the trade; absent for takers and non-Talos exchanges.
    MakerPermit2Message:
      type: object
      description: The maker Permit2 message for signature registration. Contains the signed Permit2 witness transfer data including maker-specific witness details with consideration and fee.
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          $ref: '#/components/schemas/TokenPermissions'
        spender:
          type: string
          description: The address of the StableFX contract
          example: '0xa8f94168b4981840ba27d423f4ad6332bedee006'
        nonce:
          type: string
          description: A unique nonce for the signature to prevent replay attacks, as a string representation of a uint256
          example: '309585810'
        deadline:
          type: string
          format: epoch
          description: The validity period for the signature in epoch seconds, as a string representation of a uint256
          example: '1770302983'
        witness:
          type: object
          description: Witness data containing maker trade details
          required:
            - consideration
            - fee
          properties:
            consideration:
              $ref: '#/components/schemas/TradeSignatureConsideration'
            fee:
              type: string
              description: The fee for the trade, as a string representation of a uint256
              example: '80000'
    RegisterTradeSignatureRequest:
      type: object
      description: Request body for submitting a maker trade signature
      required:
        - tradeId
        - address
        - details
        - signature
      properties:
        tradeId:
          $ref: '#/components/schemas/Id'
        address:
          type: string
          description: The wallet address signing the trade presign data
          example: '0x1234567890abcdef1234567890abcdef12345678'
        details:
          $ref: '#/components/schemas/MakerPermit2Message'
        signature:
          type: string
          description: The signature generated from signing the trade presign data
    RegisterTradeSignatureResponse:
      type: object
      description: Response from registering a trade signature
      required:
        - tradeId
        - createDate
        - updateDate
      properties:
        tradeId:
          $ref: '#/components/schemas/Id'
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
    Fee:
      type: object
      description: The fee details for a trade
      properties:
        tradeId:
          $ref: '#/components/schemas/Id'
        fee:
          $ref: '#/components/schemas/CurrencyAmount'
    TradePresignData:
      type: object
      description: Permit2 EIP-712 Typed Data for Trade Registration
      required:
        - typedData
      properties:
        typedData:
          $ref: '#/components/schemas/TradeTypedData'
    FundingMode:
      type: string
      description: |
        The funding mode for funding requests.
        - `gross`: the trader delivers the full amount for each trade.
        - `net`: the maker delivers the net difference across trades. Supported for maker funding requests only.
        - `delegate`: a funder wallet delivers tokens on the trader's behalf. The trader signs a zero-amount Permit2 authorization and the funder signs the Permit2 transfer carrying the delivery amount.
      enum:
        - gross
        - net
        - delegate
      default: gross
    FundingPresign:
      type: object
      description: Request body for generating funding presign data
      required:
        - contractTradeIds
        - type
      properties:
        contractTradeIds:
          type: array
          description: List of contract trade IDs. Exactly one contract trade ID is supported when `fundingMode` is `delegate`.
          example:
            - '10'
            - '11'
            - '12'
          items:
            type: string
          minItems: 1
        type:
          $ref: '#/components/schemas/Type'
        fundingMode:
          allOf:
            - $ref: '#/components/schemas/FundingMode'
          description: Funding mode for the presign request. `net` is supported for maker funding requests only; `delegate` is supported for both maker and taker.
        funderAddress:
          type: string
          description: Address of the funder wallet that will deliver tokens on the trader's behalf. Required when `fundingMode` is `delegate`.
          example: '0x1234567890abcdef1234567890abcdef12345678'
        recipientAddress:
          type: string
          description: Address that receives the delivered tokens. Required when `fundingMode` is `delegate`.
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
    EIP712TypeProperty:
      type: object
      description: A single property definition in EIP-712 types
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: The name of the property
        type:
          type: string
          description: The type of the property
    SinglePermit2EIP712Types:
      type: object
      description: EIP-712 type definitions for single Permit2 transfer
      required:
        - EIP712Domain
        - TokenPermissions
        - SingleTradeWitness
        - PermitWitnessTransferFrom
      properties:
        EIP712Domain:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: name
              type: string
            - name: chainId
              type: uint256
            - name: verifyingContract
              type: address
        TokenPermissions:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: token
              type: address
            - name: amount
              type: uint256
        SingleTradeWitness:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: id
              type: uint256
        PermitWitnessTransferFrom:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: permitted
              type: TokenPermissions
            - name: spender
              type: address
            - name: nonce
              type: uint256
            - name: deadline
              type: uint256
            - name: witness
              type: SingleTradeWitness
    SingleTradeWitness:
      type: object
      description: Single trade witness data
      required:
        - id
      properties:
        id:
          type: string
          description: The trade ID
          example: '10'
    Permit2SingleFundingMessage:
      type: object
      description: The message data for Permit2 signature
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          $ref: '#/components/schemas/TokenPermissions'
        spender:
          type: string
          description: The spender contract address
          example: '0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE'
        nonce:
          type: string
          description: The nonce for the permit, as a string representation of a uint256
          example: '42'
        deadline:
          type: string
          description: The deadline timestamp for the permit, as a string representation of a uint256
          example: '1735689600'
        witness:
          $ref: '#/components/schemas/SingleTradeWitness'
    SinglePermit2TypedData:
      type: object
      description: EIP-712 typed data structure for single Permit2 transfer
      required:
        - domain
        - types
        - primaryType
        - message
      properties:
        domain:
          $ref: '#/components/schemas/Permit2EIP712Domain'
        types:
          $ref: '#/components/schemas/SinglePermit2EIP712Types'
        primaryType:
          type: string
          description: The primary type for the EIP-712 signature
          example: PermitWitnessTransferFrom
        message:
          $ref: '#/components/schemas/Permit2SingleFundingMessage'
    Permit2EIP712Types:
      type: object
      description: Permit2 EIP-712 type definitions
      required:
        - EIP712Domain
        - TokenPermissions
        - BatchTradeWitness
        - PermitWitnessBatchTransferFrom
      properties:
        EIP712Domain:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: name
              type: string
            - name: chainId
              type: uint256
            - name: verifyingContract
              type: address
        TokenPermissions:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: token
              type: address
            - name: amount
              type: uint256
        BatchTradeWitness:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: ids
              type: uint256[]
        PermitWitnessBatchTransferFrom:
          type: array
          items:
            $ref: '#/components/schemas/EIP712TypeProperty'
          example:
            - name: permitted
              type: TokenPermissions[]
            - name: spender
              type: address
            - name: nonce
              type: uint256
            - name: deadline
              type: uint256
            - name: witness
              type: BatchTradeWitness
    BatchTradeWitness:
      type: object
      description: Batch trade witness data with multiple IDs
      required:
        - ids
      properties:
        ids:
          type: array
          description: Array of trade IDs
          items:
            type: string
          example:
            - '10'
            - '11'
            - '12'
    Permit2BatchFundingMessage:
      type: object
      description: The message data for Permit2 batch signature
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          type: array
          description: Array of token permissions
          items:
            $ref: '#/components/schemas/TokenPermissions'
          example:
            - token: 0xTOKEN1
              amount: '1000'
            - token: 0xTOKEN2
              amount: '2000'
        spender:
          type: string
          description: The spender contract address
          example: '0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE'
        nonce:
          type: string
          description: The nonce for the permit, as a string representation of a uint256
          example: '42'
        deadline:
          type: string
          description: The deadline timestamp for the permit, as a string representation of a uint256
          example: '1735689600'
        witness:
          $ref: '#/components/schemas/BatchTradeWitness'
    BatchPermit2TypedData:
      type: object
      description: EIP-712 typed data structure for batch Permit2 transfer
      required:
        - domain
        - types
        - primaryType
        - message
      properties:
        domain:
          $ref: '#/components/schemas/Permit2EIP712Domain'
        types:
          $ref: '#/components/schemas/Permit2EIP712Types'
        primaryType:
          type: string
          description: The primary type for the EIP-712 signature
          example: PermitWitnessBatchTransferFrom
        message:
          $ref: '#/components/schemas/Permit2BatchFundingMessage'
    DelegateFundingAuthorization:
      type: object
      description: DelegateFundingAuthorization witness binding the Permit2 authorization to a specific trade, funder, recipient, token, and amount.
      required:
        - id
        - funder
        - recipient
        - token
        - amount
      properties:
        id:
          type: string
          description: On-chain trade id (uint256).
          example: '987654321'
        funder:
          type: string
          description: Address of the funder wallet (Circle-controlled) authorized to deliver tokens on the trader's behalf.
          example: 0xLLCFunderPW...address
        recipient:
          type: string
          description: Address that receives the delivered tokens.
          example: 0xLLCEscrowPW...address
        token:
          type: string
          description: ERC-20 contract address of the token to be delivered.
          example: 0xMXNB...address
        amount:
          type: string
          description: Amount to be delivered by the funder, in token units (uint256, no decimals). Tokens use 6 decimal places, so 5000.00 MXNB is represented as "5000000000".
          example: '5000000000'
    DelegateFundingPermit2:
      type: object
      description: Permit2 PermitWitnessTransferFrom payload with DelegateFundingAuthorization witness. The `permitted.amount` is always 0 -- Permit2 is used as an authorization carrier, no tokens transfer from the trader.
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          $ref: '#/components/schemas/TokenPermissions'
        spender:
          type: string
          description: FxEscrow contract address.
          example: 0xFxEscrow000000000000000000000000000000000
        nonce:
          type: string
          description: Permit2 nonce, as a string representation of a uint256.
          example: '1234567890'
        deadline:
          type: string
          description: Permit2 deadline (unix timestamp), as a string representation of a uint256.
          example: '1782556800'
        witness:
          $ref: '#/components/schemas/DelegateFundingAuthorization'
    Permit2TypedData:
      type: object
      description: EIP-712 Permit2 typed-data envelope for trader signing.
      required:
        - types
        - primaryType
        - domain
        - message
      properties:
        types:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EIP712TypeProperty'
        primaryType:
          type: string
          example: DelegateFundingAuthorizationPermitWitnessTransferFrom
        domain:
          $ref: '#/components/schemas/Permit2EIP712Domain'
        message:
          $ref: '#/components/schemas/DelegateFundingPermit2'
    DelegateFundingWitness:
      type: object
      description: DelegateFundingWitness signed by the funder when delivering tokens on a trader's behalf. Both the trader (via DelegateFundingAuthorization) and the funder independently commit to the same recipient, and the contract verifies agreement on-chain. The funder address is not part of the witness because Permit2 verifies the signer identity via the `owner` parameter.
      required:
        - id
        - recipient
      properties:
        id:
          type: string
          description: On-chain trade id (uint256).
          example: '987654321'
        recipient:
          type: string
          description: Address that receives the delivered tokens. Must match the recipient in the trader's DelegateFundingAuthorization.
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
    DelegateFundingFunderPermit2:
      type: object
      description: Permit2 PermitWitnessTransferFrom payload signed by the funder when delivering tokens on a trader's behalf. Unlike the trader's authorization payload, this permit carries the actual delivery amount in `permitted.amount`. The DelegateFundingWitness binds the funder's signature to a specific trade and recipient, and must agree with the trader's DelegateFundingAuthorization.
      required:
        - permitted
        - spender
        - nonce
        - deadline
        - witness
      properties:
        permitted:
          $ref: '#/components/schemas/TokenPermissions'
        spender:
          type: string
          description: FxEscrow contract address.
          example: 0xFxEscrow000000000000000000000000000000000
        nonce:
          type: string
          description: Permit2 nonce, as a string representation of a uint256.
          example: '1234567890'
        deadline:
          type: string
          description: Permit2 deadline (unix timestamp), as a string representation of a uint256.
          example: '1782556800'
        witness:
          $ref: '#/components/schemas/DelegateFundingWitness'
    FunderPermit2TypedData:
      type: object
      description: EIP-712 Permit2 typed-data envelope for funder signing.
      required:
        - types
        - primaryType
        - domain
        - message
      properties:
        types:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EIP712TypeProperty'
        primaryType:
          type: string
          example: DelegateFundingPermitWitnessTransferFrom
        domain:
          $ref: '#/components/schemas/Permit2EIP712Domain'
        message:
          $ref: '#/components/schemas/DelegateFundingFunderPermit2'
    FundingPresign-2:
      description: Response containing Permit2 EIP-712 typed data for funding operations. For `gross` and `net` funding modes, contains the trader's Permit2 typed data along with deliverables and receivables. For `delegate` funding mode, contains separate typed-data payloads for the trader and the funder. No discriminator is defined because the response body carries no `fundingMode` field; the variant is determined by the `fundingMode` sent in the request, and the two variants have mutually exclusive required properties.
      oneOf:
        - type: object
          title: TraderFundingPresign
          description: Presign data for `gross` and `net` funding modes.
          required:
            - typedData
            - deliverables
            - receivables
          properties:
            deliverables:
              type: array
              description: Aggregated assets that the trader needs to deliver.
              items:
                $ref: '#/components/schemas/CurrencyAmount'
            receivables:
              type: array
              description: Aggregated assets that the trader expects to receive after fee deduction.
              items:
                $ref: '#/components/schemas/CurrencyAmount'
            typedData:
              oneOf:
                - $ref: '#/components/schemas/SinglePermit2TypedData'
                - $ref: '#/components/schemas/BatchPermit2TypedData'
              discriminator:
                propertyName: primaryType
                mapping:
                  PermitWitnessTransferFrom: '#/components/schemas/SinglePermit2TypedData'
                  PermitWitnessBatchTransferFrom: '#/components/schemas/BatchPermit2TypedData'
        - type: object
          title: DelegateFundingPresign
          description: Presign data for `delegate` funding mode.
          required:
            - traderPermitTypedData
            - funderPermitTypedData
          properties:
            traderPermitTypedData:
              allOf:
                - $ref: '#/components/schemas/Permit2TypedData'
              description: The trader's delegate-funding authorization typed data. The trader signs this zero-amount Permit2 payload to authorize the funder to deliver on their behalf.
            funderPermitTypedData:
              allOf:
                - $ref: '#/components/schemas/FunderPermit2TypedData'
              description: The funder's delegate-funding typed data. The funder signs this Permit2 payload, which carries the actual delivery amount.
    Fund:
      type: object
      description: Request body for funding operations
      required:
        - type
        - signature
        - permit2
      properties:
        type:
          $ref: '#/components/schemas/Type'
        signature:
          type: string
          description: The trader's Permit2 signature over `permit2`
          example: 0x1234567890abcdef...
        fundingMode:
          allOf:
            - $ref: '#/components/schemas/FundingMode'
            - type:
                - string
                - 'null'
          description: The funding mode for the operation (optional)
        permit2:
          oneOf:
            - $ref: '#/components/schemas/Permit2SingleFundingMessage'
            - $ref: '#/components/schemas/Permit2BatchFundingMessage'
            - $ref: '#/components/schemas/DelegateFundingPermit2'
          discriminator:
            propertyName: witness
            mapping:
              SingleTradeWitness: '#/components/schemas/Permit2SingleFundingMessage'
              BatchTradeWitness: '#/components/schemas/Permit2BatchFundingMessage'
              DelegateFundingAuthorization: '#/components/schemas/DelegateFundingPermit2'
          description: The Permit2 message object signed by the trader. Single or batch funding message for `gross`/`net` funding modes; delegate-funding authorization (with `permitted.amount` of 0) when `fundingMode` is `delegate`.
        funderPermit2:
          allOf:
            - $ref: '#/components/schemas/DelegateFundingFunderPermit2'
          description: The Permit2 message object signed by the funder, carrying the actual delivery amount. Required when `fundingMode` is `delegate`.
        funderSignature:
          type: string
          description: The funder's Permit2 signature over `funderPermit2`. Required when `fundingMode` is `delegate`.
          example: 0xabcdef1234567890...
    XRequestId:
      type: string
      description: A unique identifier, which can be helpful for identifying a request when communicating with Circle support.
      example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
      format: uuid
    NotificationType:
      type: string
      description: |
        The type of notification that can be subscribed to. 
        Supports wildcard patterns (e.g., 'stablefx.trade.*') to subscribe to all notifications within a category.
        The '*' wildcard can be used to subscribe to all notifications.
      enum:
        - '*'
        - stablefx.trade.*
        - stablefx.trade.confirmed
        - stablefx.trade.pendingSettlement
        - stablefx.trade.makerFunded
        - stablefx.trade.makerDelegateFunded
        - stablefx.trade.takerFunded
        - stablefx.trade.takerDelegateFunded
        - stablefx.trade.completed
        - stablefx.trade.refunded
        - stablefx.trade.failed
        - stablefx.trade.breached
        - stablefx.contract.*
        - stablefx.contract.recordTrade.failed
        - stablefx.contract.makerDeliver.failed
        - stablefx.contract.makerDelegateDeliver.failed
        - stablefx.contract.takerDeliver.failed
        - stablefx.contract.takerDelegateDeliver.failed
      example: stablefx.trade.confirmed
    Subscription:
      type: object
      title: Subscription
      description: Contains information about a webhook notification subscription.
      required:
        - id
        - name
        - endpoint
        - enabled
        - createDate
        - updateDate
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          type: string
          description: Name of the webhook notification subscription.
          example: Transactions Webhook
        endpoint:
          type: string
          description: URL of the endpoint subscribing to notifications. Must be enabled to receive notifications.
          example: https://example.org/handler/for/notifications
        enabled:
          type: boolean
          description: Whether the subscription is enabled. `true` indicates the subscription is enabled.
          example: true
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
        notificationTypes:
          type: array
          description: The notification types on which a notification will be sent.
          items:
            $ref: '#/components/schemas/NotificationType'
          example:
            - '*'
        restricted:
          type: boolean
          description: Whether the webhook is restricted to specific notification types. An unrestricted webhook will notify on all notification types. A restricted webhook will only notify on the notification types in the `notificationTypes` field.
          example: false
    Subscriptions:
      title: SubscriptionsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    ErrorCode:
      title: ErrorCode
      type: integer
      description: The code that corresponds to the error.
      enum:
        - -1
        - 0
        - 1
        - 2
        - 3
        - 400
        - 401
        - 403
        - 404
    DescriptiveErrorType:
      title: DescriptiveErrorType
      type: string
      enum:
        - MISSING_OR_INVALID_FIELD
      description: Type of descriptive error
    DescriptiveError:
      title: DescriptiveError
      type: object
      required:
        - error
        - message
      properties:
        error:
          $ref: '#/components/schemas/DescriptiveErrorType'
        location:
          type:
            - string
            - 'null'
          description: The key or path where the error occurred
        message:
          type: string
          description: Detailed description of the error
    CreateSubscription:
      title: SubscriptionResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
    Subscription-2:
      title: SubscriptionResponse
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
    NotificationSignaturePublicKey:
      title: NotificationSignaturePublicKeyResponse
      type: object
      properties:
        data:
          type: object
          required:
            - id
            - algorithm
            - publicKey
            - createDate
          properties:
            id:
              type: string
              format: uuid
              example: 09379bc1-4871-45ad-8b8b-8027795df70d
            algorithm:
              type: string
              example: ECDSA_SHA_256
            publicKey:
              type: string
              example: QFkwewylAoZIzj0CBQYIKoZIzj0DAQcDQgAEEext6d7AimvYFDAKBwsUsGXrhqmRHNPYum7V/BwfvJLmJeSMe2V0b9eWKPuFxAEH8HCY/MSZdBI+q/E6IdPnSg==
            createDate:
              type: string
              example: '2023-06-01T18:18:06.931526Z'
    Error:
      title: Error
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Human-readable message that describes the error.
          example: Unknown error occurred
        errors:
          type: array
          description: Array of detailed error descriptions
          items:
            $ref: '#/components/schemas/DescriptiveError'
    SettlementAdvanceCurrency:
      type: string
      description: Currency code for settlement advance flows.
      example: USDC
    SettlementAdvanceCurrencyAmount:
      type: object
      description: Currency and amount for settlement advance flows.
      required:
        - currency
        - amount
      properties:
        currency:
          $ref: '#/components/schemas/SettlementAdvanceCurrency'
        amount:
          $ref: '#/components/schemas/Amount'
    SettlementAdvanceCreditUsage:
      type: object
      description: Credit line usage breakdown.
      required:
        - used
        - available
        - availableInCurrencies
        - outstandingTransfers
      properties:
        used:
          $ref: '#/components/schemas/Amount'
        available:
          $ref: '#/components/schemas/Amount'
        availableInCurrencies:
          type: object
          description: Available credit per currency.
          additionalProperties:
            $ref: '#/components/schemas/Amount'
          example:
            USDC: '350000.00'
            MXNB: '6020000.00'
        outstandingTransfers:
          type: integer
          description: Number of outstanding credit transfers.
          example: 3
    SettlementAdvanceCredit:
      type: object
      description: Settlement advance credit line view.
      required:
        - status
        - limit
        - usage
        - fees
        - createDate
        - updateDate
      properties:
        status:
          type: string
          description: Credit line status.
          enum:
            - active
            - inactive
            - onboarding
          example: active
        limit:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        usage:
          $ref: '#/components/schemas/SettlementAdvanceCreditUsage'
        fees:
          description: Fee schedule applicable to this credit line.
          type: object
          required:
            - recurringFee
            - drawFee
            - reservationFee
          properties:
            recurringFee:
              description: Hourly fee rate charged on the outstanding advance balance, in basis points.
              $ref: '#/components/schemas/Amount'
            drawFee:
              description: One-time fee charged when a settlement advance is drawn, in basis points.
              $ref: '#/components/schemas/Amount'
            reservationFee:
              description: Fee charged when credit is reserved, in basis points.
              $ref: '#/components/schemas/Amount'
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
    ReserveSettlementAdvance:
      type: object
      description: Request body for reserving settlement advance credit.
      required:
        - idempotencyKey
        - advance
      properties:
        idempotencyKey:
          $ref: '#/components/schemas/IdempotencyKey'
        advance:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
    ReservationStatus:
      type: string
      description: |
        Status of a settlement advance reservation.
        - `active` -- reservation is live; holds available-balance capacity on the credit line.
        - `expired` -- reservation window elapsed without an origination claiming it; terminal state.
        - `consumed` -- origination claimed this reservation; terminal state.
        - `canceled` -- reservation voided by admin or system action; terminal state.
      enum:
        - active
        - expired
        - consumed
        - canceled
      example: active
    SettlementAdvanceReservation:
      type: object
      description: Settlement advance reservation.
      required:
        - id
        - amount
        - status
        - expirationDate
      properties:
        id:
          $ref: '#/components/schemas/Id'
        amount:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        status:
          $ref: '#/components/schemas/ReservationStatus'
        expirationDate:
          $ref: '#/components/schemas/ExpireDate'
        createDate:
          $ref: '#/components/schemas/CreateDate'
    SettlementAdvanceReservations:
      type: object
      description: List of settlement advance reservations.
      required:
        - reservations
      properties:
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/SettlementAdvanceReservation'
    PresignSettlementAdvance:
      type: object
      description: Request body for getting settlement advance Permit2 typed-data.
      required:
        - tradeId
      properties:
        tradeId:
          type: string
          description: Trade identifier.
          example: trade-abc-123
    SettlementAdvancePresign:
      type: object
      description: Settlement advance Permit2 typed-data for maker signing.
      required:
        - advance
        - collateral
        - makerPermitTypedData
      properties:
        advance:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        collateral:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        makerPermitTypedData:
          $ref: '#/components/schemas/Permit2TypedData'
    AdvanceCreditStatus:
      type: string
      description: |
        Lifecycle status of the credit advanced against a settlement.
        - `funds_reserved` -- credit reserved on the line, awaiting maker action.
        - `requested` -- maker submitted the request; Circle is moving funds.
        - `disbursed` -- funds delivered to the funder passthrough wallet.
        - `past_due` -- repayment window has elapsed without full repayment.
        - `paid` -- credit fully repaid.
        - `rejected` -- credit line rejected the advance request.
        - `expired` -- reservation expired before being consumed.
        - `canceled` -- maker or Circle canceled the advance.
      enum:
        - funds_reserved
        - requested
        - disbursed
        - past_due
        - paid
        - rejected
        - expired
        - canceled
      example: disbursed
    SettlementAdvanceHistory:
      type: object
      description: List of settlement advances.
      required:
        - advances
      properties:
        advances:
          type: array
          items:
            type: object
            required:
              - advanceId
              - advance
              - collateral
              - status
              - createDate
            properties:
              advanceId:
                $ref: '#/components/schemas/Id'
              advance:
                $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
              collateral:
                $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
              status:
                $ref: '#/components/schemas/AdvanceCreditStatus'
              createDate:
                $ref: '#/components/schemas/CreateDate'
              dueDate:
                type:
                  - string
                  - 'null'
                format: date-time
                description: When the advance is due to be repaid in full. Null until funded.
    AcceptSettlementAdvance:
      type: object
      description: Request body for accepting a settlement advance by submitting a Permit2 signature.
      required:
        - idempotencyKey
        - tradeId
        - permit2
        - signature
      properties:
        idempotencyKey:
          $ref: '#/components/schemas/IdempotencyKey'
        tradeId:
          type: string
          description: Trade identifier.
          example: trade-abc-123
        permit2:
          $ref: '#/components/schemas/DelegateFundingPermit2'
        signature:
          type: string
          description: Maker's Permit2 signature over the typed data (0x-prefixed, 65 bytes hex).
          example: 0x6f5a...c1b9
    SettlementAdvanceAccepted:
      type: object
      description: Settlement advance accepted; funding in progress.
      required:
        - advanceId
        - tradeId
        - status
      properties:
        advanceId:
          $ref: '#/components/schemas/Id'
        tradeId:
          $ref: '#/components/schemas/Id'
        status:
          $ref: '#/components/schemas/AdvanceCreditStatus'
    RepaymentRecord:
      type: object
      description: A single repayment applied against a settlement advance.
      required:
        - id
        - amount
        - settlementDate
        - createDate
      properties:
        id:
          description: Repayment identifier.
          $ref: '#/components/schemas/Id'
        amount:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        settlementDate:
          type: string
          format: date-time
          description: When the repayment settled on-chain.
        createDate:
          type: string
          format: date-time
          description: When the repayment was first recorded.
    SettlementAdvanceDetail:
      type: object
      description: Full detail of a single settlement advance.
      required:
        - advanceId
        - tradeId
        - status
        - advance
        - collateral
        - createDate
      properties:
        advanceId:
          description: Settlement advance identifier.
          $ref: '#/components/schemas/Id'
        tradeId:
          type: string
          description: Trade identifier.
          example: trade-abc-123
        advance:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        collateral:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        fees:
          description: Fee projection for this advance.
          type: object
          properties:
            total:
              description: Final fee charged for the advance. Populated once fully repaid.
              oneOf:
                - $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
                - type: 'null'
            unpaid:
              description: Fee accrued but not yet collected.
              oneOf:
                - $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
                - type: 'null'
        status:
          $ref: '#/components/schemas/AdvanceCreditStatus'
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
        paidDate:
          type:
            - string
            - 'null'
          format: date-time
          description: When the settlement advance was paid. Null until paid.
        dueDate:
          type:
            - string
            - 'null'
          format: date-time
          description: When the advance is due to be repaid in full. Null until paid.
        repayments:
          type: array
          description: Repayments applied against this advance.
          items:
            $ref: '#/components/schemas/RepaymentRecord'
    RepaySettlementAdvance:
      type: object
      description: Request body for repaying a settlement advance.
      required:
        - idempotencyKey
        - amount
      properties:
        idempotencyKey:
          $ref: '#/components/schemas/IdempotencyKey'
        amount:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
    RepaymentStatus:
      type: string
      description: Status of a settlement advance repayment.
      enum:
        - pending
        - completed
        - failed
      example: pending
    SettlementAdvanceRepayment:
      type: object
      description: Settlement advance repayment.
      required:
        - id
        - amount
        - status
        - createDate
        - updateDate
      properties:
        id:
          $ref: '#/components/schemas/Id'
        amount:
          $ref: '#/components/schemas/SettlementAdvanceCurrencyAmount'
        status:
          $ref: '#/components/schemas/RepaymentStatus'
        createDate:
          $ref: '#/components/schemas/CreateDate'
        updateDate:
          $ref: '#/components/schemas/UpdateDate'
    TenancyEnvironment:
      description: The tenancy environment of the trade.
      type: string
      enum:
        - TEST
        - LIVE
      example: TEST
    Webhook:
      type: object
      description: A webhook payload
      properties:
        clientId:
          $ref: '#/components/schemas/Id'
        notification:
          $ref: '#/components/schemas/TradeDetail'
        tenancyEnvironment:
          $ref: '#/components/schemas/TenancyEnvironment'
        messageTraceId:
          $ref: '#/components/schemas/Id'
        userId:
          type:
            - 'null'
        userGroupTypes:
          type: array
          description: The user group types.
          default: []
          items:
            type: string
  parameters:
    Status:
      name: status
      description: The status of the trade to filter by.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/TradeStatus'
    Asset:
      name: asset
      description: Filter trades by one or more asset currencies.
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Currency'
        minItems: 1
      style: form
      explode: true
    Id:
      name: id
      description: Filter trades by a single trade ID or ID prefix.
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 36
    Ids:
      name: ids
      description: Filter trades by one or more trade IDs.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          format: uuid
        minItems: 1
      style: form
      explode: true
    PageSize:
      name: pageSize
      description: |
        Limits the number of items to be returned.

        Some collections have a strict upper bound that will disregard this value. In case the specified value is higher
        than the allowed limit, the collection limit will be used.

        If avoided, the collection will determine the page size itself.
      in: query
      schema:
        type: integer
        default: 50
        maximum: 200
        minimum: 1
    From:
      name: from
      description: Queries items created since the specified date-time (inclusive) in ISO 8601 format.
      in: query
      schema:
        type: string
        format: date-time
        example: '2023-01-01T12:04:05Z'
    To:
      name: to
      description: Queries items created before the specified date-time (inclusive) in ISO 8601 format.
      in: query
      schema:
        type: string
        format: date-time
        example: '2023-01-01T12:04:05Z'
    XRequestId:
      name: X-Request-Id
      description: Developer-provided parameter used to identify this request. Useful when communicating with Circle Support.
      in: header
      schema:
        $ref: '#/components/schemas/XRequestId'
    Id-2:
      name: id
      description: The universally unique identifier of the resource.
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: b3d9d2d5-4c12-4946-a09d-953e82fae2b0
  headers:
    Link:
      required: true
      description: |
        Cursor pagination links for the collection, emitted as one relation per `Link` header value.

        `first` and `self` are always returned. `prev` is returned when a previous page exists and `next`
        when more results follow; the absence of `next` means the last page has been reached.

        Each URL replays the filters from the original request and carries the `pageAfter` or `pageBefore`
        cursor together with `pageSize`. Follow these URLs instead of assembling cursors yourself.
      schema:
        type: string
      example: <https://api.circle.com/v1/exchange/stablefx/trades?type=taker&pageSize=50&pageAfter=04a4892d-eef4-4df9-a5a4-4ccfc43497d6>; rel="next"
    XRequestId:
      description: |
        Circle-generated universally unique identifier (UUID v4). Useful for identifying a specific request when communicating with Circle Support.
      schema:
        $ref: '#/components/schemas/XRequestId'
  responses:
    NotAuthorized:
      content:
        application/json:
          schema:
            type: object
            title: NotAuthorizedResponse
            required:
              - code
              - message
            properties:
              code:
                $ref: '#/components/schemas/ErrorCode'
              message:
                type: string
                description: Human-readable message that describes the error.
                example: Unknown error occurred
              errors:
                type: array
                description: Array of detailed error descriptions
                items:
                  $ref: '#/components/schemas/DescriptiveError'
            example:
              code: 401
              message: Malformed authorization.
      description: Request has not been applied because it lacks valid authentication credentials.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
    BadRequest:
      content:
        application/json:
          schema:
            type: object
            title: BadRequestResponse
            required:
              - code
              - message
            properties:
              code:
                $ref: '#/components/schemas/ErrorCode'
              message:
                type: string
                description: Human-readable message that describes the error.
                example: Unknown error occurred
              errors:
                type: array
                description: Array of detailed error descriptions
                items:
                  $ref: '#/components/schemas/DescriptiveError'
            example:
              code: 400
              message: Bad request.
      description: Request cannot be processed due to a client error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
    NotFound:
      content:
        application/json:
          schema:
            type: object
            title: NotFoundResponse
            required:
              - code
              - message
            properties:
              code:
                $ref: '#/components/schemas/ErrorCode'
              message:
                type: string
                description: Human-readable message that describes the error.
                example: Unknown error occurred
              errors:
                type: array
                description: Array of detailed error descriptions
                items:
                  $ref: '#/components/schemas/DescriptiveError'
            example:
              code: 404
              message: Not found.
      description: Specified resource was not found.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
    DefaultError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Error response
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
  requestBodies:
    CreateSubscription:
      content:
        application/json:
          schema:
            description: Required parameters to create a new subscription.
            type: object
            required:
              - endpoint
            properties:
              endpoint:
                type: string
                description: URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request.
                example: https://example.org/handler/for/notifications
              notificationTypes:
                type: array
                description: The notification types to subscribe to. If not provided, the webhook will be unrestricted, and a notification is sent for every notification type. If the wildcard (`*`) or any combination of the wildcard and a set of notification types is provided, the webhook will also be unrestricted. If a set of notification types are provided, the webhook will be restricted. The restricted status of the webhook is returned in the response object. Each category of notification types also has a wildcard, which will restrict to all notification types from that category.
                items:
                  $ref: '#/components/schemas/NotificationType'
                example:
                  - '*'
      required: true
      description: Schema for the request payload to create a new subscription.
    UpdateSubscription:
      content:
        application/json:
          schema:
            type: object
            required:
              - name
              - enabled
            properties:
              name:
                type: string
                description: Name of the subscription.
                example: Trades Webhook
              enabled:
                type: boolean
                description: Whether the subscription is enabled. `true` indicates the subscription is active.
                example: true
      required: true
      description: Schema for the request payload to update a subscription.