openapi: 3.0.3
info:
  title: TeleSwap API
  version: "2.0"
  description: |
    The TeleSwap REST API powers TeleSwap — the Bitcoin DeFi hub for bridging,
    swapping, and earning on Bitcoin (BTC ⇄ EVM, TON & Solana).

    The [`@teleportdao/teleswap-sdk`](https://www.npmjs.com/package/@teleportdao/teleswap-sdk)
    wraps these endpoints; you can also call them directly.

    **Authentication:** the endpoints documented here are public and require no API key.
    A separate set of endpoints (not listed here) requires an API key — contact the team
    on [Discord](https://discord.com/invite/2mYJBB9bGR) for access.
servers:
  - url: https://api.teleportdao.xyz
    description: Production
tags:
  - name: Estimates
    description: Quote output amounts and fees before building a transaction.
  - name: Transactions
    description: Build unsigned transactions / contract-call inputs.
  - name: Requests
    description: Look up status and history of bridge/swap requests.

paths:
  /api/v2/teleswap/utils/wrap-and-swap-estimate:
    post:
      tags: [Estimates]
      summary: Estimate wrapAndSwap (BTC → EVM/TON)
      operationId: wrapAndSwapEstimate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amountBTC, networkName]
              properties:
                amountBTC:
                  type: string
                  example: "0.001"
                networkName:
                  type: string
                  example: "optimism"
                outputToken:
                  type: string
                  description: Target token contract address. Omit for the native token.
                thirdPartyId:
                  type: integer
      responses:
        "200":
          description: Estimate
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WrapAndSwapEstimate" }

  /api/v2/teleswap/utils/swap-and-unwrap-estimate:
    post:
      tags: [Estimates]
      summary: Estimate swapAndUnwrap (EVM → BTC)
      operationId: swapAndUnwrapEstimate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [exchangeInfo, networkName]
              properties:
                exchangeInfo: { $ref: "#/components/schemas/ExchangeInfo" }
                networkName:
                  type: string
                  example: "optimism"
                thirdPartyId:
                  type: integer
      responses:
        "200":
          description: Estimate
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SwapAndUnwrapEstimate" }

  /api/v2/teleswap/utils/swap-and-unwrap-estimate-ton:
    post:
      tags: [Estimates]
      summary: Estimate swapAndUnwrap (TON → BTC)
      operationId: swapAndUnwrapEstimateTon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [exchangeInfo]
              properties:
                exchangeInfo: { $ref: "#/components/schemas/ExchangeInfo" }
                thirdPartyId:
                  type: integer
      responses:
        "200":
          description: Estimate
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SwapAndUnwrapEstimate" }

  /api/v2/teleswap/utils/wrap-and-swap-unsigned:
    post:
      tags: [Transactions]
      summary: Build unsigned wrapAndSwap tx (BTC → EVM/TON)
      operationId: wrapAndSwapUnsigned
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recipientAddress, amountBTC, signer, networkName]
              properties:
                recipientAddress:
                  type: string
                  example: "0x4e3e1807aa17aed8d1FC580dDa552079d9427ece"
                amountBTC:
                  type: string
                  example: "0.001"
                signer: { $ref: "#/components/schemas/Signer" }
                networkName:
                  type: string
                  example: "ethereum"
                outputToken:
                  type: string
                minOutputAmount:
                  type: string
                changeAddress:
                  type: string
                staticFeeRate:
                  type: number
                staticUTXO:
                  type: array
                  items: { type: object }
                thirdPartyId:
                  type: integer
      responses:
        "200":
          description: Unsigned transaction payload
          content:
            application/json:
              schema: { type: object }

  /api/v2/teleswap/utils/swap-and-unwrap-inputs:
    post:
      tags: [Transactions]
      summary: Get swapAndUnwrap contract-call inputs (EVM → BTC)
      operationId: swapAndUnwrapInputs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [exchangeInfo, bitcoinAddress, networkName]
              properties:
                exchangeInfo: { $ref: "#/components/schemas/ExchangeInfo" }
                bitcoinAddress:
                  type: string
                networkName:
                  type: string
                minBtcAmount:
                  type: string
                thirdPartyId:
                  type: integer
      responses:
        "200":
          description: Contract-call inputs (call BurnRouter on base networks, EthConnector on cross-chain)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ContractInputs" }

  /api/v2/teleswap/utils/swap-and-unwrap-inputs-ton:
    post:
      tags: [Transactions]
      summary: Get swapAndUnwrap contract-call inputs (TON → BTC)
      operationId: swapAndUnwrapInputsTon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [exchangeInfo, bitcoinAddress, networkName]
              properties:
                exchangeInfo: { $ref: "#/components/schemas/ExchangeInfo" }
                bitcoinAddress:
                  type: string
                networkName:
                  type: string
                minBtcAmount:
                  type: string
                thirdPartyId:
                  type: integer
      responses:
        "200":
          description: TON message payload + raw params
          content:
            application/json:
              schema: { type: object }

  /api/v2/teleswap/requests/tx/{txId}:
    get:
      tags: [Requests]
      summary: Get transaction status by TXID
      operationId: getRequestStatusByTxId
      parameters:
        - name: txId
          in: path
          required: true
          schema: { type: string }
          description: A Bitcoin, EVM, or TON transaction id.
      responses:
        "200":
          description: Request record
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Request" }

  /api/v2/teleswap/requests:
    get:
      tags: [Requests]
      summary: Get account history
      operationId: getRequests
      parameters:
        - name: userAddresses
          in: query
          required: true
          schema:
            type: array
            items: { type: string }
          description: One or more Bitcoin/EVM addresses.
        - name: createdAtAfter
          in: query
          schema: { type: string, format: date-time }
        - name: createdAtBefore
          in: query
          schema: { type: string, format: date-time }
        - name: tokenType
          in: query
          schema: { type: string, enum: [BTC] }
        - name: type
          in: query
          schema: { type: string, enum: [Wrap, Unwrap, WrapAndSwap, SwapAndUnwrap] }
        - name: tokenAddress
          in: query
          schema: { type: string }
        - name: network
          in: query
          schema: { type: string }
        - name: filter
          in: query
          schema: { type: string, enum: [all, done, pending], default: done }
        - name: thirdPartyId
          in: query
          schema: { type: integer }
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
        - name: order
          in: query
          schema: { type: string, enum: [asc, desc] }
      responses:
        "200":
          description: List of requests
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Request" }

  /api/v1/teleswap/cross-chain/waiting-request/{address}:
    get:
      tags: [Requests]
      summary: Get waiting requests for an EVM address
      operationId: getWaitingRequests
      description: |
        Requests in the **Waiting** status are not returned by `GET /requests`.
        Use this endpoint to retrieve them for an EVM address.
      parameters:
        - name: address
          in: path
          required: true
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        "200":
          description: Waiting requests
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Request" }

components:
  schemas:
    ExchangeInfo:
      type: object
      required: [inputAmount]
      properties:
        inputToken:
          type: string
          description: Input token contract address. Omit for the native token.
        inputAmount:
          type: string
          description: Amount in the token's smallest unit (e.g. wei). EVM decimals 18, TON 9.
          example: "50000000000000000000"
        isFixedToken:
          type: boolean
    Signer:
      type: object
      required: [addressType, publicKey, address]
      properties:
        addressType:
          type: string
          enum: [p2wpkh, p2pkh, p2sh-p2wpkh]
        publicKey:
          type: string
        address:
          type: string
    TeleswapFee:
      type: object
      properties:
        networkFeeBTC: { type: string, example: "0.00001000" }
        protocolFeeBTC: { type: string, example: "0.00000000" }
        lockerFeeBTC: { type: string, example: "0.00000100" }
        thirdPartyFeeBTC: { type: string, example: "0.00000000" }
        totalFeeBTC: { type: string, example: "0.00001100" }
    WrapAndSwapEstimate:
      type: object
      properties:
        minInputAmountBTC: { type: string }
        inputAmountBTC: { type: string }
        outputAmount: { type: string }
        teleswapFee: { $ref: "#/components/schemas/TeleswapFee" }
        internalExchange: { type: object }
        internalBridge:
          type: object
          nullable: true
    SwapAndUnwrapEstimate:
      type: object
      properties:
        inputAmount: { type: string }
        outputAmountBTC: { type: string }
        minInputAmountBTC: { type: string }
        teleswapFee: { $ref: "#/components/schemas/TeleswapFee" }
        internalExchange: { type: object }
        internalBridge:
          type: object
          nullable: true
    ContractInputs:
      type: object
      properties:
        locker:
          type: object
          properties:
            sourceAddress: { type: string }
            targetAddress: { type: string }
            lockingScript: { type: string }
        inputs:
          type: object
          properties:
            params:
              type: array
              items: {}
            value: { type: string }
    Request:
      type: object
      description: A bridge/swap request record. See the SDK "Data models" guide for full field docs.
      properties:
        id: { type: string }
        type:
          type: string
          enum: [Wrap, Unwrap, WrapAndSwap, SwapAndUnwrap]
        tokenType:
          type: string
          enum: [BTC]
        state:
          type: string
          enum: [Pending, Done, Failed]
        status:
          type: string
          enum: [NotProcessed, Pending, Confirmed, Submitted, ExchangeFailed, Failed, Withdrawn]
        fromAddress: { type: string }
        toAddress: { type: string }
        inputTokenAmount: { type: string }
        outputTokenAmount: { type: string }
        totalFee: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
