openapi: 3.0.3
info:
  title: Tristero Assets Pricing API
  description: Tristero is a cross-chain trading protocol supporting spot swaps, margin positions, and feather (UTXO-based) swaps. This API provides endpoints for requesting quotes, submitting orders, managing margin positions, and real-time updates via WebSocket.
  version: 2.0.0
  contact:
    name: Tristero Support
    url: https://tristero.com
servers:
- url: https://api.tristero.com/v2
  description: Production
- url: https://staging-api.tristero.com/v2
  description: Staging
- url: http://localhost:8060
  description: Local (Quoter)
- url: http://localhost:8070
  description: Local (Filler)
security:
- ApiKeyAuth: []
tags:
- name: Pricing
paths:
  /price:
    get:
      operationId: getPrice
      summary: Get price quote
      description: Returns a live price quote for a swap between two assets. Optionally computes a worked example for a specific input or output amount.
      tags:
      - Pricing
      parameters:
      - name: input_asset
        in: query
        required: true
        schema:
          type: string
          example: BTC
        description: Asset you are sending (e.g. BTC)
      - name: output_asset
        in: query
        required: true
        schema:
          type: string
          example: ETH
        description: Asset you want to receive (e.g. ETH)
      - name: input_amount
        in: query
        required: false
        schema:
          type: number
          format: float
          example: 0.5
        description: If provided, compute the expected output for this input amount
      - name: output_amount
        in: query
        required: false
        schema:
          type: number
          format: float
          example: 5.0
        description: If provided, estimate the required input to receive this output amount
      responses:
        '200':
          description: Price information for the requested swap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceInfo'
              examples:
                basicQuote:
                  summary: Basic price quote
                  value:
                    InputAsset:
                      AssetName: BTC
                      UsdMarketMid: 65432.18
                      HalfSpread: 0.0012
                      MarketHalfSpread: 0.0008
                      HalfFee: 0.00015
                      MinAmount: 0.001
                      MaxOutput: 10.5
                      MaxInput: 15.0
                      PriceImpactRate: 5.0e-05
                      CapacityFraction: 0.73
                      TargetBalance: 20.0
                      CurrentBalance: 14.6
                      FundingAddress: bc1qfeatherfundingaddress1234567890abcdef
                    OutputAsset:
                      AssetName: ETH
                      UsdMarketMid: 3456.78
                      HalfSpread: 0.0008
                      MarketHalfSpread: 0.0005
                      HalfFee: 0.0025
                      MinAmount: 0.01
                      MaxOutput: 150.0
                      MaxInput: 200.0
                      PriceImpactRate: 2.0e-05
                      CapacityFraction: 0.85
                      TargetBalance: 200.0
                      CurrentBalance: 170.0
                      FundingAddress: 0xFeatherFundingAddress1234567890abcdef1234
                    ExchangeRate: 18.92
                    InputFee: 0.0003
                    MaxInput: 10.5
                    MinInput: 0.001
                    MaxOutput: 150.0
                quoteWithInputAmount:
                  summary: Quote with input amount example
                  value:
                    InputAsset:
                      AssetName: BTC
                      UsdMarketMid: 65432.18
                      HalfSpread: 0.0012
                      MarketHalfSpread: 0.0008
                      HalfFee: 0.00015
                      MinAmount: 0.001
                      MaxOutput: 10.5
                      MaxInput: 15.0
                      PriceImpactRate: 5.0e-05
                      CapacityFraction: 0.73
                      TargetBalance: 20.0
                      CurrentBalance: 14.6
                      FundingAddress: bc1qfeatherfundingaddress1234567890abcdef
                    OutputAsset:
                      AssetName: ETH
                      UsdMarketMid: 3456.78
                      HalfSpread: 0.0008
                      MarketHalfSpread: 0.0005
                      HalfFee: 0.0025
                      MinAmount: 0.01
                      MaxOutput: 150.0
                      MaxInput: 200.0
                      PriceImpactRate: 2.0e-05
                      CapacityFraction: 0.85
                      TargetBalance: 200.0
                      CurrentBalance: 170.0
                      FundingAddress: 0xFeatherFundingAddress1234567890abcdef1234
                    ExchangeRate: 18.92
                    InputFee: 0.0003
                    MaxInput: 10.5
                    MinInput: 0.001
                    MaxOutput: 150.0
                    Example:
                      InputAmount: 0.5
                      InputUsd: 32716.09
                      OutputAmount: 9.42
                      OutputUsd: 32562.86
                      Overpay: 0.0
                      Warning: ''
components:
  schemas:
    PriceInfo:
      type: object
      example:
        InputAsset:
          AssetName: BTC
          UsdMarketMid: 65432.18
          HalfSpread: 0.0012
          MarketHalfSpread: 0.0008
          HalfFee: 0.00015
          MinAmount: 0.001
          MaxOutput: 10.5
          MaxInput: 15.0
          PriceImpactRate: 5.0e-05
          CapacityFraction: 0.73
          TargetBalance: 20.0
          CurrentBalance: 14.6
          FundingAddress: bc1qfeatherfundingaddress1234567890abcdef
        OutputAsset:
          AssetName: ETH
          UsdMarketMid: 3456.78
          HalfSpread: 0.0008
          MarketHalfSpread: 0.0005
          HalfFee: 0.0025
          MinAmount: 0.01
          MaxOutput: 150.0
          MaxInput: 200.0
          PriceImpactRate: 2.0e-05
          CapacityFraction: 0.85
          TargetBalance: 200.0
          CurrentBalance: 170.0
          FundingAddress: 0xFeatherFundingAddress1234567890abcdef1234
        ExchangeRate: 18.92
        InputFee: 0.0003
        MaxInput: 10.5
        MinInput: 0.001
        MaxOutput: 150.0
      properties:
        InputAsset:
          $ref: '#/components/schemas/AssetPrice'
        OutputAsset:
          $ref: '#/components/schemas/AssetPrice'
        ExchangeRate:
          type: number
          format: float
          description: Output units per input unit at the current mid-price
          example: 18.92
        InputFee:
          type: number
          format: float
          description: On-chain fee deducted from your deposit before exchange
          example: 0.0003
        MaxInput:
          type: number
          format: float
          description: Maximum deposit Feather will accept on this route right now
          example: 10.5
        MinInput:
          type: number
          format: float
          description: Minimum deposit Feather will process
          example: 0.001
        MaxOutput:
          type: number
          format: float
          description: Maximum Feather will pay out
          example: 150.0
        Example:
          $ref: '#/components/schemas/ExecutedTrade'
          description: Present if input_amount or output_amount was supplied
      required:
      - InputAsset
      - OutputAsset
      - ExchangeRate
      - InputFee
      - MaxInput
      - MinInput
      - MaxOutput
    AssetPrice:
      type: object
      example:
        AssetName: BTC
        UsdMarketMid: 65432.18
        HalfSpread: 0.0012
        MarketHalfSpread: 0.0008
        HalfFee: 0.00015
        MinAmount: 0.001
        MaxOutput: 10.5
        MaxInput: 15.0
        PriceImpactRate: 5.0e-05
        CapacityFraction: 0.73
        TargetBalance: 20.0
        CurrentBalance: 14.6
        FundingAddress: bc1qfeatherfundingaddress1234567890abcdef
      properties:
        AssetName:
          type: string
          description: Asset identifier (e.g. "BTC")
          example: BTC
        UsdMarketMid:
          type: number
          format: float
          description: Current USD mid-market price
          example: 65432.18
        HalfSpread:
          type: number
          format: float
          description: Half the bid-ask spread applied to trades
        MarketHalfSpread:
          type: number
          format: float
          description: External market half-spread for reference
        HalfFee:
          type: number
          format: float
          description: Estimated half of the on-chain fee in asset units
        MinAmount:
          type: number
          format: float
          description: Minimum deposit amount Feather will process
        MaxOutput:
          type: number
          format: float
          description: Maximum amount Feather will pay out of this asset
        MaxInput:
          type: number
          format: float
          description: Maximum amount Feather will accept as input
        PriceImpactRate:
          type: number
          format: float
          description: λ — rate of price adjustment per unit traded
        CapacityFraction:
          type: number
          format: float
          description: Current balance as a fraction of target
        TargetBalance:
          type: number
          format: float
          description: Target balance in asset units
        CurrentBalance:
          type: number
          format: float
          description: Current liquid balance in asset units
        FundingAddress:
          type: string
          description: Feather's main address for this asset (for funding/monitoring)
      required:
      - AssetName
      - UsdMarketMid
      - HalfSpread
      - MarketHalfSpread
      - HalfFee
      - MinAmount
      - MaxOutput
      - MaxInput
      - PriceImpactRate
      - CapacityFraction
      - TargetBalance
      - CurrentBalance
      - FundingAddress
    ExecutedTrade:
      type: object
      example:
        InputAmount: 0.5
        InputUsd: 32716.09
        OutputAmount: 9.42
        OutputUsd: 32562.86
        Overpay: 0.0
        Warning: ''
      properties:
        InputAmount:
          type: number
          format: float
          description: Input amount used in the calculation
          example: 0.5
        InputUsd:
          type: number
          format: float
          description: USD value of the input
          example: 32716.09
        OutputAmount:
          type: number
          format: float
          description: Expected output amount
          example: 9.42
        OutputUsd:
          type: number
          format: float
          description: USD value of the output
          example: 32562.86
        Overpay:
          type: number
          format: float
          description: Amount exceeding the cap that would be returned
          example: 0.0
        Warning:
          type: string
          description: Describes why execution would be degraded
          example: ''
      required:
      - InputAmount
      - InputUsd
      - OutputAmount
      - OutputUsd
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication (if required by deployment)
externalDocs:
  description: Tristero Python SDK Documentation
  url: https://pypi.org/project/tristero/