openapi: 3.1.0
info:
  title: Swap by Blanc
  description: API used by Blanc Swap
  version: 1.0.0-beta

security:
  - BasicAuth: []

servers:
  - url: https://swaps.sprinter.tech/mainnet
    description: Mainnet Swap API
  - url: https://swaps.sprinter.tech/base
    description: Base Swap API

paths:
  /v1/route:
    get:
      operationId: getRouteV1
      description: Calculate the optimal swap route and generate execution parameters for a token exchange
      parameters:
        - in: query
          name: amountIn
          description: The amount of input tokens to swap (in token's smallest unit)
          schema:
            $ref: "#/components/schemas/TokenAmount"
          required: true
        - in: query
          name: tokenIn
          description: Contract address of the input token to sell. The zero address (0x00…00) represents the native currency ETH.
          schema:
            $ref: "#/components/schemas/Address"
          required: true
        - in: query
          name: tokenOut
          description: Contract address of the output token to buy. The zero address (0x00…00) represents the native currency ETH.
          schema:
            $ref: "#/components/schemas/Address"
          required: true
        - in: query
          name: slippageBps
          description: The slippage tolerance in basis points (e.g., 50 for 0.5%)
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 10000
            default: 50
          required: false
        - in: query
          name: timeout
          description: Optional timeout in milliseconds. If set, returns the best pathfinder result within the timeout window. Must be a positive integer.
          schema:
            type: integer
            format: int32
            minimum: 1
          required: false
      responses:
        200:
          description: Successfully calculated swap route with execution details
          headers:
            Request-ID:
              $ref: "#/components/headers/RequestID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteV1Response"
        400:
          description: Bad request due to invalid parameters
          headers:
            Request-ID:
              $ref: "#/components/headers/RequestID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized access due to invalid or missing credentials
          headers:
            Request-ID:
              $ref: "#/components/headers/RequestID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: No viable swap route found for the given parameters
          headers:
            Request-ID:
              $ref: "#/components/headers/RequestID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          headers:
            Request-ID:
              $ref: "#/components/headers/RequestID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

  headers:
    RequestID:
      description: Unique request identifier (16 bytes) encoded as hexadecimal with 0x prefix
      schema:
        $ref: "#/components/schemas/RequestID"

  schemas:
    RequestID:
      description: Unique request identifier (16 bytes) encoded as hexadecimal with 0x prefix
      type: string
      format: hex
      pattern: "^0x[a-fA-F0-9]{32}$"

    Address:
      description: Ethereum contract address (20 bytes) encoded as hexadecimal with 0x prefix
      type: string
      pattern: "^0x[a-fA-F0-9]{40}$"

    Bytes:
      description: Arbitrary byte data encoded as hexadecimal with 0x prefix
      type: string
      pattern: "^0x[a-fA-F0-9]*$"

    TokenAmount:
      description: Amount of an ERC20 token as a decimal string (no scientific notation)
      type: string
      pattern: "^[0-9]+$"

    RouteV1Response:
      description: Successfully created route with execution details
      type: object
      required:
        [
          requestId,
          amountOut,
          minAmountOut,
          target,
          callData,
          gasUsed,
          gasLimit,
        ]
      properties:
        requestId:
          $ref: "#/components/schemas/RequestID"
        amountOut:
          description: Amount of tokens to receive
          $ref: "#/components/schemas/TokenAmount"
        minAmountOut:
          description: Minimum amount of tokens to receive after slippage
          $ref: "#/components/schemas/TokenAmount"
        target:
          description: The target contract address for the swap
          $ref: "#/components/schemas/Address"
        callData:
          description: Hex encoded calldata for the swap
          $ref: "#/components/schemas/Bytes"
        gasUsed:
          description: Actual gas consumed by the swap simulation
          type: integer
          format: uint64
          minimum: 0
          example: 180000
        gasLimit:
          description: Recommended gas limit for the swap transaction (gasUsed * 1.3)
          type: integer
          format: uint64
          minimum: 0
          example: 234000

    Error:
      description: Error response with details
      type: object
      required: [code, requestId, error]
      properties:
        code:
          description: Error code indicating the type of error
          type: integer
        requestId:
          $ref: "#/components/schemas/RequestID"
        error:
          description: Error message
          type: string