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://api.jup.ag/swap/v1

paths:
  /quote:
    get:
      tags:
        - Swap
      summary: quote
      description: "Retrieve a quote to be used in `POST /swap`.\n\nRefer to https://station.jup.ag/docs/swap-api/get-quote for more information."
      parameters:
        - in: query
          name: inputMint
          schema:
            type: string
          required: true
          description: Input token mint address
        - in: query
          name: outputMint
          schema:
            type: string
          required: true
          description: Output token mint address
        - in: query
          name: amount
          schema:
            type: number
          required: true
          description: Amount of input token
        - in: query
          name: slippageBps
          schema:
            type: number
          description: Slippage in basis points
        - in: query
          name: swapMode
          schema:
            $ref: '#/components/schemas/SwapMode'
          description: Swap mode (ExactIn or ExactOut)
        - in: query
          name: dexes
          schema:
            type: array
            items:
              type: string
          description: List of DEXes to include
        - in: query
          name: excludeDexes
          schema:
            type: array
            items:
              type: string
          description: List of DEXes to exclude
        - in: query
          name: restrictIntermediateTokens
          schema:
            type: boolean
          description: Whether to restrict intermediate tokens
        - in: query
          name: onlyDirectRoutes
          schema:
            type: boolean
          description: Whether to only use direct routes
        - in: query
          name: asLegacyTransaction
          schema:
            type: boolean
          description: Whether to use legacy transaction
        - in: query
          name: platformFeeBps
          schema:
            type: number
          description: Platform fee in basis points
        - in: query
          name: maxAccounts
          schema:
            type: number
          description: Maximum number of accounts
      responses:
        '200':
          description: "Successful response\n- To be used in /swap"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
  /swap:
    post:
      tags:
        - Swap
      summary: swap
      description: "Returns a transaction that you can use from the quote you get from `/quote`.\n\nRefer to https://station.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-instructions:
    post:
      tags:
        - Swap
      summary: swap-instructions
      description: "Returns instructions that you can use from the quote you get from `/quote`.\n\nRefer to https://station.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'
  /program-id-to-label:
    get:
      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. With that, we can use 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 algorithm\n- Exlcuding network fees, slippage or platform fees"
        otherAmountThreshold:
          type: string
          description: "- Calculated minimum output amount after accounting for `slippageBps` and `platformFeeBps`\n- Not used by 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
          description: Time taken to determine quote

    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:
          description: The user public key
          type: string
        wrapAndUnwrapSol:
          description: "Default: true\n- To automatically wrap/unwrap SOL in the transaction\n- If false, it will use wSOL token account\n- 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: "Default: true\n- 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\n- If true, you do not need to handle the creation of intermediate token accounts for the user."
          type: boolean
          default: true
        feeAccount:
          description: "- An Associated Token Address (ATA) of specific mints depending on `SwapMode` to collect fees\n- You no longer need the Referral Program\n- 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\n- Useful for integrators to get all the swap transactions from this public key\n- 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\n- It can be used for EITHER priority fee OR Jito tip\n- 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:
                  description: Either `medium`, `high` or `veryHigh`
                  type: string
                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\n- Estimate how much to set using Jito tip percentiles endpoint\n- It has to be used together with a connection to a Jito RPC\n- [See their docs](https://docs.jito.wtf/)"
        asLegacyTransaction:
          description: "Default: false\n- Request a legacy transaction rather than the default versioned transaction\n- 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\n- If not provided, the signer's ATA will be used\n- If provided, we assume that the token account is already initialized"
          type: string
        dynamicComputeUnitLimit:
          description: "Default: false\n- When enabled, it will do a swap simulation to get the compute unit used and set it in ComputeBudget's compute unit limit\n- This will increase latency slightly since there will be one extra RPC call to simulate this\n- This can be useful to estimate compute unit correctly and reduce priority fees needed or have higher chance to be included in a block"
          type: boolean
        skipUserAccountsRpcCalls:
          description: "Default: false\n- When enabled, it will not do any additional RPC calls to check on user's accounts\n- 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
        dynamicSlippage:
          description: "Default: false\n- When enabled, it estimate slippage and apply it in the swap transaction directly, overwriting the `slippageBps` parameter in the quote response.\n- [See notes for more information](/docs/swap-api/send-swap-transaction#how-jupiter-estimates-slippage)"
          type: boolean
        computeUnitPriceMicroLamports:
          description: "- To specify a compute unit price to calculate priority fee\n- `computeUnitLimit (1400000) * computeUnitPriceMicroLamports`\n- **We recommend using `prioritizationFeeLamports` and `dynamicComputeUnitLimit` instead of passing in a compute unit price**"
          type: integer
        quoteResponse:
          $ref: '#/components/schemas/QuoteResponse'

    SwapResponse:
      type: object
      properties:
        swapTransaction:
          type: string
        lastValidBlockHeight:
          type: number
        prioritizationFeeLamports:
          type: number
        prioritizationType:
          type: object
          description: The type of prioritization used for the swap, either Jito or ComputeBudget.
          properties:
            jito:
              type: object
              properties:
                lamports:
                  type: integer
            computeBudget:
              type: object
              properties:
                estimatedMicroLamports:
                  type: integer
                microLamports:
                  type: integer

      required:
        - swapTransaction
        - lastValidBlockHeight

    SwapInstructionsResponse:
      type: object
      properties:
        computeBudgetInstructions:
          description: The necessary instructions to setup the compute budget.
          type: array
          items:
            $ref: '#/components/schemas/Instruction'
        setupInstructions:
          description: Setup missing ATA for the users.
          type: array
          items:
            $ref: '#/components/schemas/Instruction'
        swapInstruction:
          description: The actual swap instruction.
          $ref: '#/components/schemas/Instruction'
        cleanupInstruction:
          description: Unwrap the SOL if `wrapAndUnwrapSol = true`.
          $ref: '#/components/schemas/Instruction'
        addressLookupTableAddresses:
          description: The lookup table addresses that you can use if you are using versioned transaction.
          type: array
          items:
            type: string
        otherInstructions:
          description: The other instructions to be used in the swap transaction.
          type: array
          items:
            $ref: '#/components/schemas/Instruction'
        computeUnitLimit:
          type: integer
        prioritizationType:
          type: object
          description: The type of prioritization used for the swap, either Jito or ComputeBudget.
          properties:
            jito:
              type: object
        prioritizationFeeLamports:
          type: integer
        blockhashWithMetadata:
          $ref: '#/components/schemas/BlockhashWithMetadata'
      required:
        - computeBudgetInstructions
        - otherInstructions
        - setupInstructions
        - swapInstruction
        - addressLookupTableAddresses
        - computeUnitLimit
        - prioritizationType
        - prioritizationFeeLamports
        - blockhashWithMetadata

    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

    BlockhashWithMetadata:
      type: object
      required:
        - blockhash
        - lastValidBlockHeight
        - fetchedAt
      properties:
        blockhash:
          type: string
          description: The blockhash as a base58 encoded string
        lastValidBlockHeight:
          type: integer
          format: uint64
          description: The last block height at which this blockhash will be valid
        fetchedAt:
          type: number
          description: The timestamp when this blockhash was fetched

  parameters:
    InputMintParameter:
      name: inputMint
      description: Input token mint address
      in: query
      required: true
      schema:
        type: string
    OutputMintParameter:
      name: outputMint
      description: Output token mint address
      in: query
      required: true
      schema:
        type: string
    AmountParameter:
      name: amount
      description: "Atomic value to swap (Before applying decimals)\n- Input Amount if `SwapMode=ExactIn`\n- Output Amount if `SwapMode=ExactOut`"
      in: query
      required: true
      schema:
        type: integer
    SlippageParameter:
      name: slippageBps
      description: "Default: 50\n- This is threshold denoted in basis points.\n- If the output amount exceeds the threshold, then the swap transaction will fail."
      in: query
      schema:
        type: integer
        default: 50
    SwapModeParameter:
      name: swapMode
      description: "Default: ExactIn\n- ExactOut is for supporting use cases where you need an exact output amount, like [payments](../swap-api/payments-through-swap)\n- In this case the slippage is on the input token."
      in: query
      schema:
        type: string
        enum:
          - ExactIn
          - ExactOut
    DexesParameter:
      name: dexes
      description: "Default: Include ALL DEXes\n- For example: `dexes=Raydium,Orca+V2,Meteora+DLMM`\n- If a DEX is indicated, the route will **only use** that DEX\n- Multiple DEXes can be pass in by comma separating them\n- [Full list of DEXes here](https://api.jup.ag/swap/v1/program-id-to-label)"
      in: query
      schema:
        type: array
        items:
          type: string
    ExcludeDexesParameter:
      name: excludeDexes
      description: "Default: Exclude NONE of the DEXes\n- For example: `dexes=Raydium,Orca+V2,Meteora+DLMM`\n- If a DEX is indicated, the route will **not use** that DEX\n- Multiple DEXes can be pass in by comma separating them\n- [Full list of DEXes here](https://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\n- This will help to reduce exposure to potential high slippage routes"
      in: query
      schema:
        type: boolean
    OnlyDirectRoutesParameter:
      name: onlyDirectRoutes
      description: "Default: false\n- Limits the routeDirect Routes limits Jupiter routing to single hop routes only"
      in: query
      schema:
        type: boolean
    AsLegacyTransactionParameter:
      name: asLegacyTransaction
      description: "Default: false\n- Instead of using versioned transaction, this will use the legacy transaction"
      in: query
      schema:
        type: boolean
    MaxAccountsParameter:
      name: maxAccounts
      description: "Recommended: 64\n- Rough estimate of the max accounts to be used for the quote\n- Useful if composing with your own accounts or to be more precise in resource accounting resulting in better routes\n- Jupiter Frontend uses a maxAccounts of 64"
      in: query
      schema:
        type: integer
    PlatformFeeBpsParameter:
      name: platformFeeBps
      description: "- Take fees in basis points from signer\n- Used together with `feeAccount` in /swap, see [Adding Fees](/docs/swap-api/add-fees-to-swap) guide"
      in: query
      schema:
        type: integer