Chainflip Broker as a Service Swap API

openapi: 3.2.0
info:
  title: Chainflip Broker as a Service Swap API
  description: Run your own Chainflip Broker without any hassle.
  version: v1
  x-onboarding:
    freeToStart: true
    noKeyNeeded:
    - /mcp
    - /assets
    - /networks
    apiKeys:
      selfServe: true
      signup: /register
      secret: false
    sandbox: Testing environment on the Chainflip Perseverance testnet; its URLs are listed at /onboarding.
    firstCall: GET /assets
    facts: /onboarding
servers:
- url: /
  description: 'Free to start. The MCP server (/mcp), /assets and /networks need no key or account; get an API key self-serve at /register, free and without payment details. Onboarding facts: /onboarding.'
tags:
- name: Swap
  description: 'Start a swap: open a deposit channel that the source asset is sent to.'
paths:
  /swap:
    get:
      tags:
      - Swap
      summary: Start a swap
      description: 'Opens a deposit channel and returns the deposit address the user sends

        `sourceAsset` to. Once the deposit arrives the swap runs and pays out to

        `destinationAddress`, with your broker fee taken. `minimumPrice`,

        `refundAddress` and `retryDurationInBlocks` protect against slippage: if the

        price cannot be met within that time, the deposit is refunded.

        `livePriceSlippageTolerancePercent` adds a limit against Chainflip''s oracle price. Optional

        parameters add Boost (Bitcoin), DCA, a commission override and up to four affiliates. Follow the

        swap with `getStatusById` or `getStatusByDepositChannel`.'
      operationId: startSwap
      parameters:
      - name: apiKey
        in: query
        description: Your partner API key. A key is required through this parameter OR the X-API-Key header; when both are present, this query parameter wins, even when it is empty, which fails validation rather than falling back to the header.
        schema:
          type: string
      - name: sourceAsset
        in: query
        description: The asset to swap from.
        required: true
        schema:
          type: string
        example: eth.eth
      - name: destinationAsset
        in: query
        description: The asset to swap to.
        required: true
        schema:
          type: string
        example: btc.btc
      - name: destinationAddress
        in: query
        description: The address on the destination chain to swap to.
        required: true
        schema:
          type: string
        example: bc1qujr7jlxeh4m20lldqh4fcsl63ff2ee6uk60g8r
      - name: commissionBps
        in: query
        description: An optional override to the charged commission bps.
        schema:
          type: integer
          format: int32
        example: 15
      - name: boostFee
        in: query
        description: Maximum accepted boost fee in basis points (100th of a percent).
        schema:
          type: integer
          format: int32
        example: 5
      - name: minimumPrice
        in: query
        description: Minimum accepted human readable price.
        required: true
        schema:
          type: number
          format: double
        example: 2768.95
      - name: refundAddress
        in: query
        description: Address on the source chain to which the refund will be sent, if the minimum price cannot be met.
        required: true
        schema:
          type: string
        example: '0x2c1f0390f27740257de9f3772d9a6bb46ec13fe3'
      - name: retryDurationInBlocks
        in: query
        description: 'Number of blocks after which a deposit is refunded if the minimum price cannot be met. One block corresponds to 6 seconds. Max 14400 = 24 hours. Recommended: 150.'
        required: true
        schema:
          type: integer
          format: int32
        example: 100
      - name: livePriceSlippageTolerancePercent
        in: query
        description: 'Live price protection: how far, in percent (0 to 100, at most 2 decimals), the execution price may fall below Chainflip''s oracle price; a swap below it is retried and, after `retryDurationInBlocks`, refunded. Use the quote''s `recommendedLivePriceSlippageTolerancePercent` when it has one. Rejected with code `live_price_protection_unavailable` when either asset has no oracle price on Chainflip. When set, a stale oracle price also counts as a violation. Omit it to keep Chainflip''s default protection for the pair.'
        schema:
          type: number
          format: double
        example: 0.5
      - name: numberOfChunks
        in: query
        description: The number of "sub-swaps" to perform for a DCA swap.
        schema:
          type: integer
          format: int32
        example: 32
      - name: chunkIntervalBlocks
        in: query
        description: The delay between the "sub-swaps" of a DCA swap in number of blocks.
        schema:
          type: integer
          format: int32
        example: 2
      - name: affiliate1
        in: query
        description: First optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate1CommissionBps
        in: query
        description: First optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: affiliate2
        in: query
        description: Second optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate2CommissionBps
        in: query
        description: Second optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: affiliate3
        in: query
        description: Third optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate3CommissionBps
        in: query
        description: Third optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: affiliate4
        in: query
        description: Fourth optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate4CommissionBps
        in: query
        description: Fourth optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: platform
        in: query
        description: Optional provider to route the swap through. Defaults to chainflip.
        schema:
          type: string
        example: chainflip
      responses:
        '200':
          description: A deposit address for the given swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainflipBaas.Swap.DepositAddress'
        '400':
          description: The request has invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: One or more validation errors occurred.
                status: 400
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
                errors:
                  apiKey:
                  - A value for the 'apiKey' parameter or property was not provided.
        '401':
          description: The partner does not have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.5.2
                title: Unauthorized
                status: 401
                detail: Invalid partner.
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
        '403':
          description: Swaps between these assets are not enabled for the partner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.5.4
                title: Forbidden
                status: 403
                detail: Swaps from BTC to ETH are not enabled for your account.
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
        '503':
          description: A temporary upstream condition, such as maintenance, a disabled asset or the network channel cap. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.6.4
                title: Service Unavailable
                status: 503
                detail: One of the assets in this swap is currently disabled on Chainflip
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
                code: asset_disabled
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.6.1
                title: An error occurred while processing your request.
                status: 500
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
      security:
      - apiKey: []
      - apiKeyHeader: []
    post:
      tags:
      - Swap
      summary: Start an advanced swap
      description: 'The same as `startSwap`, plus a JSON body for parameters that do not fit in a

        query string, such as a Cross-Chain Messaging payload for the destination chain.'
      operationId: startAdvancedSwap
      parameters:
      - name: apiKey
        in: query
        description: Your partner API key. A key is required through this parameter OR the X-API-Key header; when both are present, this query parameter wins, even when it is empty, which fails validation rather than falling back to the header.
        schema:
          type: string
      - name: sourceAsset
        in: query
        description: The asset to swap from.
        required: true
        schema:
          type: string
        example: eth.eth
      - name: destinationAsset
        in: query
        description: The asset to swap to.
        required: true
        schema:
          type: string
        example: btc.btc
      - name: destinationAddress
        in: query
        description: The address on the destination chain to swap to.
        required: true
        schema:
          type: string
        example: bc1qujr7jlxeh4m20lldqh4fcsl63ff2ee6uk60g8r
      - name: commissionBps
        in: query
        description: An optional override to the charged commission bps.
        schema:
          type: integer
          format: int32
        example: 15
      - name: boostFee
        in: query
        description: Maximum accepted boost fee in basis points (100th of a percent).
        schema:
          type: integer
          format: int32
        example: 5
      - name: minimumPrice
        in: query
        description: Minimum accepted human readable price.
        required: true
        schema:
          type: number
          format: double
        example: 2768.95
      - name: refundAddress
        in: query
        description: Address on the source chain to which the refund will be sent, if the minimum price cannot be met.
        required: true
        schema:
          type: string
        example: '0x2c1f0390f27740257de9f3772d9a6bb46ec13fe3'
      - name: retryDurationInBlocks
        in: query
        description: 'Number of blocks after which a deposit is refunded if the minimum price cannot be met. One block corresponds to 6 seconds. Max 14400 = 24 hours. Recommended: 150.'
        required: true
        schema:
          type: integer
          format: int32
        example: 100
      - name: livePriceSlippageTolerancePercent
        in: query
        description: 'Live price protection: how far, in percent (0 to 100, at most 2 decimals), the execution price may fall below Chainflip''s oracle price; a swap below it is retried and, after `retryDurationInBlocks`, refunded. Use the quote''s `recommendedLivePriceSlippageTolerancePercent` when it has one. Rejected with code `live_price_protection_unavailable` when either asset has no oracle price on Chainflip. When set, a stale oracle price also counts as a violation. Omit it to keep Chainflip''s default protection for the pair.'
        schema:
          type: number
          format: double
        example: 0.5
      - name: numberOfChunks
        in: query
        description: The number of "sub-swaps" to perform for a DCA swap.
        schema:
          type: integer
          format: int32
        example: 32
      - name: chunkIntervalBlocks
        in: query
        description: The delay between the "sub-swaps" of a DCA swap in number of blocks.
        schema:
          type: integer
          format: int32
        example: 2
      - name: affiliate1
        in: query
        description: First optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate1CommissionBps
        in: query
        description: First optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: affiliate2
        in: query
        description: Second optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate2CommissionBps
        in: query
        description: Second optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: affiliate3
        in: query
        description: Third optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate3CommissionBps
        in: query
        description: Third optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: affiliate4
        in: query
        description: Fourth optional extra affiliate ss58 address to share commission with.
        schema:
          type: string
        example: cFMTcq3p1C4Yhpw7NPn88Jdzj6ryVD8cTGPBuVMR4U6tFVdQb
      - name: affiliate4CommissionBps
        in: query
        description: Fourth optional extra affiliate commission in basis points.
        schema:
          type: integer
          format: int32
        example: 10
      - name: platform
        in: query
        description: Optional provider to route the swap through. Defaults to chainflip.
        schema:
          type: string
        example: chainflip
      requestBody:
        description: 'Advanced swap parameters which are not supported as query string parameters, e.g.: Cross-Chain Messaging payload.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChainflipBaas.Swap.AdvancedSwapRequest'
      responses:
        '200':
          description: A deposit address for the given swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainflipBaas.Swap.DepositAddress'
        '400':
          description: The request has invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: One or more validation errors occurred.
                status: 400
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
                errors:
                  apiKey:
                  - A value for the 'apiKey' parameter or property was not provided.
        '401':
          description: The partner does not have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.5.2
                title: Unauthorized
                status: 401
                detail: Invalid partner.
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
        '403':
          description: Swaps between these assets are not enabled for the partner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.5.4
                title: Forbidden
                status: 403
                detail: Swaps from BTC to ETH are not enabled for your account.
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
        '503':
          description: A temporary upstream condition, such as maintenance, a disabled asset or the network channel cap. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.6.4
                title: Service Unavailable
                status: 503
                detail: One of the assets in this swap is currently disabled on Chainflip
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
                code: asset_disabled
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc9110#section-15.6.1
                title: An error occurred while processing your request.
                status: 500
                traceId: 00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00
      security:
      - apiKey: []
      - apiKeyHeader: []
components:
  schemas:
    Microsoft.AspNetCore.Mvc.ValidationProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization(e.g., using proactive content negotiation; see[RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: The validation errors associated with this problem details.
      additionalProperties:
        description: Problem type definitions MAY extend the problem details object with additional members. Extension members appear in the same namespace as other members of a problem type.
      description: 'A request that failed input validation (RFC 9457 problem details): `errors` lists the messages per parameter.'
    ChainflipBaas.Swap.AdvancedSwapRequest:
      type: object
      properties:
        ccmPayload:
          $ref: '#/components/schemas/ChainflipBaas.Swap.CcmRequest'
      additionalProperties: false
      description: The parameters of `startAdvancedSwap` that do not fit in a query string.
    Microsoft.AspNetCore.Mvc.ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization(e.g., using proactive content negotiation; see[RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        code:
          type: string
          description: 'A stable, machine-readable error code (lowercase snake_case, e.g. "asset_disabled") identifying why the request failed, so clients can branch without matching the human-readable `detail` text. The HTTP status follows the code: 400 when the request as sent cannot be fulfilled, 404 when a status lookup found nothing to answer with, 503 for a temporary upstream condition, 500 when unclassified. Omitted when the failure has no classification. Clients must tolerate both an omitted code and unrecognised future values. See the Error codes reference: https://docs.chainflip-broker.io/features/error-codes'
          example: asset_disabled
      additionalProperties:
        description: Problem type definitions MAY extend the problem details object with additional members. Extension members appear in the same namespace as other members of a problem type.
      description: An error response (RFC 9457 problem details). Branch on `code` when it is present, never on the `detail` text.
    ChainflipBaas.Swap.CcmRequest:
      required:
      - gas_budget
      - message
      type: object
      properties:
        gas_budget:
          minLength: 1
          pattern: ^[0-9]+$
          type: string
          description: Gas budget for the call on the destination chain. This amount is based on the source asset and will be subtracted from the input amount and swapped to pay for gas.
          example: '100000'
        message:
          maxLength: 20002
          minLength: 0
          pattern: ^0x[0-9a-fA-F]*$
          type: string
          description: Hex-encoded message that is passed to the destination address on the destination chain. The message should be shorter than 10k bytes.
          example: '0xdeadc0de'
      additionalProperties: false
      description: Cross-Chain Messaging payload. More details can be found at https://docs.chainflip.io/swapping/integrations/advanced/cross-chain-messaging/cross-chain-messaging
    ChainflipBaas.Swap.DepositAddress:
      required:
      - address
      - channelId
      - channelOpeningFee
      - channelOpeningFeeNative
      - destinationAddress
      - explorerUrl
      - issuedBlock
      - network
      - sourceExpiryBlock
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
          description: 'The BaaS swap id: pass it as `swapId` to `getStatusById`. Absent in the rare case the swap

            could not be recorded right away; follow it with `getStatusByDepositChannel` then.'
          format: int32
          example: 42
        address:
          type: string
          description: The deposit address to send source assets to.
          example: '0x8127c88e8b5a92917486bc68a4b481befab12534'
        issuedBlock:
          type: integer
          description: The block in which the deposit address was issued.
          format: int64
          example: 1504251
        network:
          type: string
          description: The network to send the source assets over.
          example: Ethereum
        channelId:
          type: integer
          description: The channel id to monitor the deposit.
          format: int64
          example: 107
        sourceExpiryBlock:
          type: integer
          description: The block (on the source network) in which the deposit address will expire.
          format: int64
          example: 850819
        explorerUrl:
          type: string
          description: The explorer url to monitor the deposit.
          example: https://scan.chainflip.io/channels/1504251-Ethereum-107
        channelOpeningFee:
          type: number
          description: Fee in $FLIP to open the deposit channel.
          format: double
          example: 0
        channelOpeningFeeNative:
          type: string
          description: Fee in $FLIP flipperinos to open the deposit channel.
          example: '0'
        destinationAddress:
          minLength: 1
          type: string
          description: 'The destination address the swap was accepted for, exactly as you sent it (no change of case, prefix or

            encoding). Always present.'
          example: bc1qujr7jlxeh4m20lldqh4fcsl63ff2ee6uk60g8r
      additionalProperties: false
      description: 'The deposit channel opened for the swap. Send the source asset to `address` on `network` before

        the channel expires at `sourceExpiryBlock`, then follow the swap with `getStatusById` (using

        `id`) or `getStatusByDepositChannel`.'
  securitySchemes:
    apiKey:
      type: apiKey
      description: Your partner API key, from registering at /register on this site. It identifies your account and is not a secret; it grants no access beyond your own partner's quotes, swaps, fees and statuses. There is no OAuth and there are no scopes. A key is also accepted in an X-API-Key request header; when both are present, this query parameter wins, even when it is empty.
      name: apiKey
      in: query
    apiKeyHeader:
      type: apiKey
      description: Your partner API key, from registering at /register on this site, sent as a request header so it does not appear in URLs that proxies and access logs capture. It identifies your account and is not a secret; it grants no access beyond your own partner's quotes, swaps, fees and statuses. There is no OAuth and there are no scopes. When an apiKey query parameter is present it wins.
      name: X-API-Key
      in: header