openapi: '3.0.2'
info:
  title: Swap API
  version: 1.0.0
  description: |
    The heart and soul of Jupiter lies in the Quote and Swap API.

    ### API Rate Limit
    Since 1 December 2024, we have updated our API structure. Please refer to [Station](https://station.jup.ag/docs/) for further details on usage and rate limits.

    ### API Usage
    - API Wrapper Typescript [@jup-ag/api](https://github.com/jup-ag/jupiter-quote-api-node)

    ### Data Types To Note
    - Public keys are base58 encoded strings
    - Raw data such as Vec<u8\> are base64 encoded strings

servers:
  - url: https://lite-api.jup.ag/swap/v1
    description: Free tier API endpoint with rate limits
  - url: https://api.jup.ag/swap/v1
    description: Paid tier API endpoint with higher rate limits to be used with an API Key

paths:
  /swap/v1/quote:
    get:
      operationId: QuoteGet
      tags:
        - Swap
      summary: quote
      description: |
        Request for a quote to be used in `POST /swap`
        
        :::note
        Refer to [Swap API doc](https://dev.jup.ag/docs/swap-api/get-quote) for more information
        :::
      parameters:
        - $ref: '#/components/parameters/InputMintParameter'
        - $ref: '#/components/parameters/OutputMintParameter'
        - $ref: '#/components/parameters/AmountParameter'
        - $ref: '#/components/parameters/SlippageParameter'
        - $ref: '#/components/parameters/SwapModeParameter'
        - $ref: '#/components/parameters/DexesParameter'
        - $ref: '#/components/parameters/ExcludeDexesParameter'
        - $ref: '#/components/parameters/RestrictIntermediateTokensParameter'
        - $ref: '#/components/parameters/OnlyDirectRoutesParameter'
        - $ref: '#/components/parameters/AsLegacyTransactionParameter'
        - $ref: '#/components/parameters/PlatformFeeBpsParameter'
        - $ref: '#/components/parameters/MaxAccountsParameter'
        - $ref: '#/components/parameters/DynamicSlippage'
      responses:
        '200':
          description: "Successful response to be used in `/swap`"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
  /swap/v1/swap:
    post:
      operationId: SwapPost
      tags:
        - Swap
      summary: swap
      description: |
        Request for a base64-encoded unsigned swap transaction based on the `/quote` response
        
        :::note
        Refer to [Swap API doc](https://dev.jup.ag/docs/swap-api/build-swap-transaction) for more information
        :::
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapResponse'
  /swap/v1/swap-instructions:
    post:
      operationId: SwapInstructionsPost
      tags:
        - Swap
      summary: swap-instructions
      description: |
        Request for swap instructions that you can use from the quote you get from `/quote`
        
        :::note
        Refer to [Swap API doc](https://dev.jup.ag/docs/swap-api/build-swap-transaction#build-your-own-transaction-with-instructions) for more information
        :::
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapInstructionsResponse'
  /swap/v1/program-id-to-label:
    get:
      operationId: ProgramIdToLabelGet
      tags:
        - Swap
      summary: program-id-to-label
      description: |
        Returns a hash, which key is the program id and value is the label.
        This is used to help map error from transaction by identifying the fault program id.
        This can be used in conjunction with the `excludeDexes` or `dexes` parameter.
      responses:
        '200':
          description: Default response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string

components:
  schemas:
    Instruction:
      type: object
      properties:
        programId:
          type: string
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountMeta'
        data:
          type: string
      required:
        - programId
        - accounts
        - data

    AccountMeta:
      type: object
      properties:
        pubkey:
          type: string
        isSigner:
          type: boolean
        isWritable:
          type: boolean
      required:
        - pubkey
        - isSigner
        - isWritable

    QuoteResponse:
      type: object
      required:
        - inputMint
        - outputMint
        - inAmount
        - outAmount
        - otherAmountThreshold
        - swapMode
        - slippageBps
        - priceImpactPct
        - routePlan
      properties:
        inputMint:
          type: string
        inAmount:
          type: string
        outputMint:
          type: string
        outAmount:
          type: string
          description: |
            - Calculated output amount from routing engine
            - Exlcuding slippage or platform fees
        otherAmountThreshold:
          type: string
          description: |
            - Calculated minimum output amount after accounting for `slippageBps` and `platformFeeBps`
            - Not used by `/swap` endpoint to build transaction
        swapMode:
          $ref: '#/components/schemas/SwapMode'
          required: true
        slippageBps:
          type: integer
          format: int32
        platformFee:
          $ref: '#/components/schemas/PlatformFee'
        priceImpactPct:
          type: string
        routePlan:
          type: array
          items:
            $ref: '#/components/schemas/RoutePlanStep'
        contextSlot:
          type: number
        timeTaken:
          type: number

    SwapMode:
      type: string
      enum:
        - ExactIn
        - ExactOut

    PlatformFee:
      type: object
      properties:
        amount:
          type: string
        feeBps:
          type: integer
          format: int32

    RoutePlanStep:
      type: object
      properties:
        swapInfo:
          $ref: '#/components/schemas/SwapInfo'
        percent:
          type: integer
          format: int32
      required:
        - swapInfo
        - percent

    SwapInfo:
      type: object
      required:
        - ammKey
        - inputMint
        - outputMint
        - inAmount
        - outAmount
        - feeAmount
        - feeMint
      properties:
        ammKey:
          type: string
        label:
          type: string
        inputMint:
          type: string
        outputMint:
          type: string
        inAmount:
          type: string
        outAmount:
          type: string
        feeAmount:
          type: string
        feeMint:
          type: string

    SwapRequest:
      type: object
      required:
        - userPublicKey
        - quoteResponse
      properties:
        userPublicKey:
          type: string
        wrapAndUnwrapSol:
          description: |
            - To automatically wrap/unwrap SOL in the transaction
            - If false, it will use wSOL token account
            - Parameter will be ignored if `destinationTokenAccount` is set because the `destinationTokenAccount` may belong to a different user that we have no authority to close
          type: boolean
          default: true
        useSharedAccounts:
          description: |
            - The default is determined dynamically by the routing engine, allowing us to optimize for compute units, etc
            - This enables the usage of shared program accounts, this is essential as complex routing will require multiple intermediate token accounts which the user might not have
            - If true, you do not need to handle the creation of intermediate token accounts for the user
            - Do note, shared accounts route will fail on some new AMMs (low liquidity token)
          type: boolean
        feeAccount:
          description: |
            - An token account that will be used to collect fees
            - The mint of the token account **can only be either the input or output mint of the swap**
            - You no longer are required to use the Referral Program
            - See [Add Fees](/docs/swap-api/add-fees-to-swap) guide for more details
          type: string
        trackingAccount:
          description: |
            - Specify any public key that belongs to you to track the transactions
            - Useful for integrators to get all the swap transactions from this public key
            - Query the data using a block explorer like Solscan/SolanaFM or query like Dune/Flipside
          type: string
        prioritizationFeeLamports:
          description: |
            - To specify a level or amount of additional fees to prioritize the transaction
            - It can be used for EITHER priority fee OR Jito tip (not both at the same time)
            - If you want to include both, you will need to use `/swap-instructions` to add both at the same time
          type: object
          properties:
            priorityLevelWithMaxLamports:
              type: object
              properties:
                priorityLevel:
                  type: string
                  enum:
                    - medium
                    - high
                    - veryHigh
                maxLamports:
                  description: |
                    - Maximum lamports to cap the priority fee estimation, to prevent overpaying
                  type: integer
            jitoTipLamports:
              type: integer
              description: |
                - Exact amount of tip to use in a tip instruction
                - Refer to Jito docs on how to estimate the tip amount based on percentiles
                - It has to be used together with a connection to a Jito RPC
                - [See their docs](https://docs.jito.wtf/)
        asLegacyTransaction:
          description: |
            - Builds a legacy transaction rather than the default versioned transaction
            - Used together with `asLegacyTransaction` in `/quote`, otherwise the transaction might be too large
          type: boolean
          default: false
        destinationTokenAccount:
          description: |
            - Public key of a token account that will be used to receive the token out of the swap
            - If not provided, the signer's token account will be used
            - If provided, we assume that the token account is already initialized
          type: string
        dynamicComputeUnitLimit:
          description: |
            - When enabled, it will do a swap simulation to get the compute unit used and set it in ComputeBudget's compute unit limit
            - This incurs one extra RPC call to simulate this
            - We recommend to enable this to estimate compute unit correctly and reduce priority fees needed or have higher chance to be included in a block
          type: boolean
          default: false
        skipUserAccountsRpcCalls:
          description: |
            - When enabled, it will not do any additional RPC calls to check on required accounts
            - Enable it only when you already setup all the accounts needed for the trasaction, like wrapping or unwrapping sol, or destination account is already created
          type: boolean
          default: false
        dynamicSlippage:
          description: |
            - When enabled, it estimates slippage and apply it in the swap transaction directly, overwriting the `slippageBps` parameter in the quote response.
            - Used together with `dynamicSlippage` in `/quote`, otherwise the slippage used will be the one in the `/quote`'s `slippageBps`
            - [See notes for more information](/docs/swap-api/send-swap-transaction#how-jupiter-estimates-slippage)
          type: boolean
          default: false
        computeUnitPriceMicroLamports:
          description: |
            - To use an exact compute unit price to calculate priority fee
            - `computeUnitLimit (1400000) * computeUnitPriceMicroLamports`
            - We recommend using `prioritizationFeeLamports` and `dynamicComputeUnitLimit` instead of passing in your own compute unit price
          type: integer
        blockhashSlotsToExpiry:
          description: |
            - Pass in the number of slots we want the transaction to be valid for
            - Example: If you pass in 10 slots, the transaction will be valid for ~400ms * 10 = approximately 4 seconds before it expires
          type: integer
        quoteResponse:
          $ref: '#/components/schemas/QuoteResponse'

    SwapResponse:
      type: object
      properties:
        swapTransaction:
          type: string
        lastValidBlockHeight:
          type: integer
        prioritizationFeeLamports:
          type: integer
      required:
        - swapTransaction
        - lastValidBlockHeight

    SwapInstructionsResponse:
      type: object
      properties:
        otherInstructions:
          description: |
            - If you set `{\"prioritizationFeeLamports\": {\"jitoTipLamports\": 5000}}`, you will see a custom tip instruction to Jito here.
          type: array
          items:
            $ref: '#/components/schemas/Instruction'
        computeBudgetInstructions:
          description: |
            - To setup the compute budget for the transaction.
          type: array
          items:
            $ref: '#/components/schemas/Instruction'
        setupInstructions:
          description: |
            - To setup required token accounts for the users.
          type: array
          items:
            $ref: '#/components/schemas/Instruction'
        swapInstruction:
          description: |
            - The actual swap instruction.
          $ref: '#/components/schemas/Instruction'
        cleanupInstruction:
          description: |
            - To unwrap the SOL if `wrapAndUnwrapSol = true`.
          $ref: '#/components/schemas/Instruction'
        addressLookupTableAddresses:
          description: |
            - The lookup table addresses if you are using versioned transaction.
          type: array
          items:
            type: string
      required:
        - computeBudgetInstructions
        - setupInstructions
        - swapInstruction
        - addressLookupTableAddresses

    IndexedRouteMapResponse:
      type: object
      required:
        - mintKeys
        - indexedRouteMap
      properties:
        mintKeys:
          type: array
          items:
            type: string
          description: All the mints that are indexed to match in indexedRouteMap
        indexedRouteMap:
          type: object
          description: All the possible route and their corresponding output mints
          additionalProperties:
            type: array
            items:
              type: number
          example:
            '1':
              - 2
              - 3
              - 4
            '2':
              - 1
              - 3
              - 4

  parameters:
    InputMintParameter:
      name: inputMint
      in: query
      required: true
      schema:
        type: string
    OutputMintParameter:
      name: outputMint
      in: query
      required: true
      schema:
        type: string
    AmountParameter:
      name: amount
      description: |
        - Raw amount to swap (before decimals)
        - Input Amount if `SwapMode=ExactIn`
        - Output Amount if `SwapMode=ExactOut`
      in: query
      required: true
      schema:
        type: integer
    SlippageParameter:
      name: slippageBps
      in: query
      schema:
        type: integer
    SwapModeParameter:
      name: swapMode
      description: |
        - ExactOut is for supporting use cases where you need an exact output amount, like using [Swap API as a payment service](/docs/swap-api/payments-through-swap)
        - In the case of `ExactIn`, the slippage is on the output token
        - In the case of `ExactOut`, the slippage is on the input token
        - Not all AMMs support `ExactOut`
      in: query
      schema:
        type: string
        enum:
          - ExactIn
          - ExactOut
        default: ExactIn
    DexesParameter:
      name: dexes
      description: |
        - Multiple DEXes can be pass in by comma separating them
        - For example: `dexes=Raydium,Orca+V2,Meteora+DLMM`
        - If a DEX is indicated, the route will **only use** that DEX
        - [Full list of DEXes here](https://lite-api.jup.ag/swap/v1/program-id-to-label)
      in: query
      schema:
        type: array
        items:
          type: string
    ExcludeDexesParameter:
      name: excludeDexes
      description: |
        - Multiple DEXes can be pass in by comma separating them
        - For example: `excludeDexes=Raydium,Orca+V2,Meteora+DLMM`
        - If a DEX is indicated, the route will **not use** that DEX
        - [Full list of DEXes here](https://lite-api.jup.ag/swap/v1/program-id-to-label)
      in: query
      schema:
        type: array
        items:
          type: string
    RestrictIntermediateTokensParameter:
      name: restrictIntermediateTokens
      description: |
        - Restrict intermediate tokens within a route to a set of more stable tokens
        - This will help to reduce exposure to potential high slippage routes
      in: query
      schema:
        type: boolean
        default: true
    OnlyDirectRoutesParameter:
      name: onlyDirectRoutes
      description: |
        - Direct Routes limits Jupiter routing to single hop routes only
        - This may result in worse routes
      in: query
      schema:
        type: boolean
        default: false
    AsLegacyTransactionParameter:
      name: asLegacyTransaction
      description: |
        - Instead of using versioned transaction, this will use the legacy transaction
      in: query
      schema:
        type: boolean
        default: false
    MaxAccountsParameter:
      name: maxAccounts
      description: |
        - Rough estimate of the max accounts to be used for the quote
        - Useful if composing your own transaction or to be more precise in resource accounting for better routes
      in: query
      schema:
        type: integer
        default: 64
    PlatformFeeBpsParameter:
      name: platformFeeBps
      description: |
        - Take fees in basis points
        - Used together with `feeAccount` in /swap, see [Adding Fees](/docs/swap-api/add-fees-to-swap) guide
      in: query
      schema:
        type: integer
    DynamicSlippage:
      name: dynamicSlippage
      description: |
        - If true, `slippageBps` will be overriden by Dynamic Slippage's estimated value
        - The value is returned in `/swap` endpoint
      in: query
      schema:
        type: boolean
        default: false