openapi: 3.0.3 info: title: Jupiter Ultra Swap API version: 1.0.0 description: Jupiter Ultra Swap API Schema servers: - url: https://api.jup.ag/ultra/v1 description: Jupiter Ultra Swap API Endpoint paths: /order: get: summary: order description: | Request for a base64-encoded unsigned swap transaction to be used in `POST /ultra/v1/execute` security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: type: object properties: mode: type: string inputMint: type: string outputMint: type: string inAmount: type: string outAmount: type: string inUsdValue: type: number outUsdValue: type: number priceImpact: type: number swapUsdValue: type: number otherAmountThreshold: type: string swapMode: type: string slippageBps: type: number priceImpactPct: type: string description: | - Please use `priceImpact` field instead, this is still available only for backwards compatibility routePlan: type: array items: type: object properties: swapInfo: type: object properties: ammKey: type: string label: type: string inputMint: type: string outputMint: type: string inAmount: type: string outAmount: type: string required: - ammKey - label - inputMint - outputMint - inAmount - outAmount percent: type: number bps: type: number usdValue: type: number required: - swapInfo - percent - bps referralAccount: type: string feeMint: type: string feeBps: type: number description: | - The fee includes either Ultra default fee or your integrator fee, depending on if referral and/or payer params are passed in - If `referralAccount`, `referralFee` (and `payer` if passed in) are passed in, the fee will be the integrator fee only - If no additional referral params are passed in, the fee will be the Ultra default fee only and can include additional fees for gasless support mechanism platformFee: type: object description: | - This field shows the platform fee only, does not include fee for gas - Platform fee can either be the Ultra default fee or your integrator fee properties: amount: type: string feeBps: type: number required: - feeBps signatureFeeLamports: type: number description: | - The number of lamports the `taker`, `maker` (JupiterZ's MM) or `payer` has to pay for the base network fee, if a valid transaction is returned. signatureFeePayer: type: string nullable: true description: | - The public key of the account that will cover the signature fee, it can be either `taker`, `maker` (JupiterZ's MM) or `payer` if passed in prioritizationFeeLamports: type: number description: | - The number of lamports the `taker`, `maker` (JupiterZ's MM) or `payer` has to pay for higher priority landing, if a valid transaction is returned - Includes priority fees and tips for services such as Jito, etc, if any prioritizationFeePayer: type: string nullable: true description: | - The public key of the account that will cover the prioritization fee, it can be either `taker`, `maker` (JupiterZ's MM) or `payer` if passed in rentFeeLamports: type: number description: | - The number of lamports the `taker` or `payer` has to pay for account rent, if a valid transaction is returned - Note that this value is just an estimate - For JupiterZ quotes, Jupiter's gas wallet pays the rent to create the taker's output token account if not yet initialised rentFeePayer: type: string nullable: true description: | - The public key of the account that will cover the rent fee, it can be either `taker`, `payer` if passed in, or Jupiter's gas wallet for JupiterZ quotes when the taker's output token account is not yet initialised swapType: type: string description: | - Deprecated, in favour of router router: type: string enum: - metis - jupiterz - dflow - okx transaction: type: string nullable: true description: | - Unsigned base-64 encoded transaction to be signed and used in `/execute` - If `taker` is null, this field will be null. - If the `transaction` field is empty, it is returned with `errorCode` and `errorMessage` such as Insufficient Funds gasless: type: boolean requestId: description: | - Required to make a request to `/execute` type: string totalTime: type: number taker: type: string nullable: true quoteId: type: string maker: type: string expireAt: type: string errorCode: type: number enum: - 1 - 2 - 3 description: | - This field will be present if `taker` is defined and `transaction` is an empty string - It is unique for each error scenarios errorMessage: type: string enum: - Insufficient funds - Top up `${solAmount}` SOL for gas - Minimum `${swapAmount}` for gasless description: | - This field will be present if `taker` is defined and `transaction` is an empty string - This field can still return despite having a valid order/quote - This is meant for display purposes only and it is discouraged to match these error messages as they could be parameterized required: - mode - inputMint - outputMint - inAmount - outAmount - otherAmountThreshold - swapMode - slippageBps - priceImpactPct - routePlan - feeBps - platformFee - signatureFeeLamports - signatureFeePayer - prioritizationFeeLamports - prioritizationFeePayer - rentFeeLamports - rentFeePayer - swapType - router - transaction - gasless - requestId - totalTime - taker example: mode: "ExactIn" inputMint: "So11111111111111111111111111111111111111112" outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" inAmount: "100000000" outAmount: "17057460" inUsdValue: 17.13 outUsdValue: 17.06 priceImpact: 0.0001 swapUsdValue: 17.06 otherAmountThreshold: "17040402" swapMode: "ExactIn" slippageBps: 1 priceImpactPct: "0.0001" routePlan: - swapInfo: ammKey: "HXpGFJGCEEFdV31tDmjDBaJMEB1fKLiAoKoWr3Fnonid" label: "Meteora DLMM" inputMint: "So11111111111111111111111111111111111111112" outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" inAmount: "100000000" outAmount: "17057460" percent: 100 bps: 10000 usdValue: 17.06 feeMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" feeBps: 5 platformFee: amount: "8529" feeBps: 5 signatureFeeLamports: 5000 signatureFeePayer: null prioritizationFeeLamports: 254600 prioritizationFeePayer: null rentFeeLamports: 0 rentFeePayer: null swapType: "aggregator" router: "metis" transaction: "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAEN..." gasless: false requestId: "b5e5f3a7-8c4d-4e2f-9a1b-3c6d8e0f2a4b" totalTime: 320 taker: "BQ72nSv9f3PRyRKCBnHLVrerrv37CYTHm5h3s9VSGQDV" '400': description: Bad request content: application/json: schema: type: object properties: error: type: string example: Failed to get quotes required: - error '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string required: - error parameters: - in: query name: inputMint schema: type: string default: "So11111111111111111111111111111111111111112" required: true - in: query name: outputMint schema: type: string default: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" required: true - in: query name: amount schema: type: string default: "10000000" required: true - in: query name: taker schema: type: string default: "BQ72nSv9f3PRyRKCBnHLVrerrv37CYTHm5h3s9VSGQDV" required: false - in: query name: receiver description: | - The public key of the account that will receive the output tokens - If not provided, the output tokens will be sent to the taker like default - It expects an account (NOT a token account) - If the output is non-SOL tokens, it only transfers to ATAs (not token accounts) - If the destination token account is not initialized, an additional create ATA instruction will be added to the transaction - If the output is SOL, it will transfer native SOL directly to the receiver account - It does not support destination WSOL token account schema: type: string required: false - in: query name: payer description: | - The public key of an account that will be used to cover 'gas-related' fees on behalf of the taker - Gas related fees such as signature fees, priority fees and rent. Note that enabling this may result in different routing decisions. - Refer to [Integrator Payer](/docs/ultra/add-payer) for more details schema: type: string required: false - in: query name: closeAuthority description: | - Optional. If used, requires `payer` - Ignored, if `payer` is not provided - The public key of an account to set as the close authority of ATAs created during the swap transaction. Only applies to non-wSOL ATAs that persist beyond the execution of the transaction. - If `closeAuthority` is not provided, we will default to `taker` - If `closeAuthority` is provided and is different from `taker`, we will add the instruction to set the new `closeAuthority` schema: type: string required: false - in: query name: referralAccount description: | - Refer to [Integrator Fees](/docs/ultra/add-fees-to-ultra) for more details schema: type: string required: false - in: query name: referralFee description: | - Refer to [Integrator Fees](/docs/ultra/add-fees-to-ultra) for more details schema: type: number minimum: 50 maximum: 255 required: false - in: query name: excludeRouters schema: type: string enum: - metis - jupiterz - dflow - okx required: false - in: query name: excludeDexes description: | - [Full list of DEXes here](https://developers.jup.ag/docs/api-reference/swap/program-id-to-label), for example: `excludeDexes=Raydium,Orca+V2,Meteora+DLMM` - **Important**: This only excludes DEXes on the Metis router, does not apply to other routers - For example: - **Exclude** Raydium: `excludeRouters=` and `excludeDexes=Raydium` - **Only include** Meteora DLMM: `excludeRouters=` and `excludeDexes=` schema: type: string /execute: post: summary: execute description: | Execute the signed transaction and get the execution status security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - Success - Failed signature: type: string slot: type: string error: type: string code: type: number totalInputAmount: type: string totalOutputAmount: type: string inputAmountResult: type: string outputAmountResult: type: string swapEvents: type: array items: type: object properties: inputMint: type: string inputAmount: type: string outputMint: type: string outputAmount: type: string required: - inputMint - inputAmount - outputMint - outputAmount required: - status - code example: status: "Success" signature: "5UfDuX7hXbTiKFJqS1MzGsNpbXTzMKJe2bZP1zrd7DnFBSChKvF2FVDNAuqz7SJpaHXTB9E5DP6tMjfZmVDMJRs" slot: "324307186" code: 0 totalInputAmount: "100000000" totalOutputAmount: "17057460" inputAmountResult: "100000000" outputAmountResult: "17057460" swapEvents: - inputMint: "So11111111111111111111111111111111111111112" inputAmount: "100000000" outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" outputAmount: "17057460" '400': description: Bad request content: application/json: schema: type: object properties: error: type: string code: type: number required: - error - code '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string code: type: number required: - error - code requestBody: content: application/json: schema: type: object properties: signedTransaction: type: string description: | - The signed transaction to execute requestId: type: string description: | - Found in response of `/order` required: - signedTransaction - requestId example: signedTransaction: "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAEN..." requestId: "b5e5f3a7-8c4d-4e2f-9a1b-3c6d8e0f2a4b" /balances/{address}: get: summary: balances deprecated: true description: | Request for token balances of an account security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: type: object additionalProperties: type: object properties: amount: type: string uiAmount: type: number slot: type: number isFrozen: type: boolean required: - amount - uiAmount - slot - isFrozen '400': description: Bad request content: application/json: schema: type: object properties: error: type: string required: - error '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string required: - error parameters: - schema: type: string in: path name: address required: true /holdings/{address}: get: summary: holdings description: | Request for token balances of an account including token account information security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: $ref: "#/components/schemas/HoldingsResponse" parameters: - schema: type: string default: "BQ72nSv9f3PRyRKCBnHLVrerrv37CYTHm5h3s9VSGQDV" in: path name: address required: true description: The wallet address to get holdings for /holdings/{address}/native: get: summary: holdings (native) description: | Request for native SOL holdings only, without other tokens security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: $ref: "#/components/schemas/NativeHoldingsResponse" parameters: - schema: type: string in: path name: address required: true description: The wallet address to get native SOL balance for /shield: get: summary: shield description: | Request for token information and warnings of mints security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: type: object properties: warnings: type: object additionalProperties: description: | - Token mint address as key type: array items: type: object properties: type: type: string enum: - NOT_VERIFIED - LOW_LIQUIDITY - NOT_SELLABLE - LOW_ORGANIC_ACTIVITY - HAS_MINT_AUTHORITY - HAS_FREEZE_AUTHORITY - HAS_PERMANENT_DELEGATE - NEW_LISTING - VERY_LOW_TRADING_ACTIVITY - HIGH_SUPPLY_CONCENTRATION - NON_TRANSFERABLE - MUTABLE_TRANSFER_FEES - SUSPICIOUS_DEV_ACTIVITY - SUSPICIOUS_TOP_HOLDER_ACTIVITY - HIGH_SINGLE_OWNERSHIP - "{}%_TRANSFER_FEES" description: | - Type of warning for the token message: type: string description: | - Human-readable warning message severity: type: string enum: - info - warning - critical description: | - Severity level of the warning source: type: string enum: - RugCheck description: | - Optional external source of the warning required: - warnings '400': description: Bad request content: application/json: schema: type: object properties: error: type: string required: - error '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string required: - error parameters: - in: query name: mints schema: type: string default: "So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" required: true description: | - Comma separated list of mints to get information for /order/routers: get: summary: routers description: | Request for the list of routers available in the routing engine of Ultra, which is [Juno](/docs/routing#juno-liquidity-engine) security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: type: array items: type: object properties: id: type: string name: type: string enum: - Metis - JupiterZ - DFlow - OKX DEX Router icon: type: string required: - id - name /search: get: summary: search description: | Request a search by token's symbol, name or mint address security: - ApiKeyAuth: [] responses: '200': description: Successful response content: application/json: schema: type: array items: "$ref": "#/components/schemas/MintInformation" '400': description: Bad request content: application/json: schema: type: object properties: error: type: string required: - error '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string required: - error parameters: - in: query name: query schema: type: string default: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" required: true description: | - Search for a token and its information by its symbol, name or mint address - Comma-separate to search for multiple - Limit to 100 mint addresses in query - Default to 20 mints in response when searching via symbol or name components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Get API key via https://developers.jup.ag/portal schemas: MintInformation: type: object properties: id: type: string description: The token's mint address name: type: string symbol: type: string icon: type: string nullable: true description: URL to the token's logo image decimals: type: number tokenProgram: type: string description: The token program address (SPL Token or Token-2022) createdAt: type: string format: date-time description: Token creation timestamp twitter: type: string nullable: true telegram: type: string nullable: true website: type: string nullable: true discord: type: string nullable: true instagram: type: string nullable: true tiktok: type: string nullable: true otherUrl: type: string nullable: true dev: type: string nullable: true description: The token's developer wallet address mintAuthority: type: string nullable: true description: Mint authority address (present when mint authority is not disabled) freezeAuthority: type: string nullable: true description: Freeze authority address (present when freeze authority is not disabled) issuer: type: string nullable: true description: Token issuer name (e.g., "Circle" for USDC) circSupply: type: number nullable: true totalSupply: type: number nullable: true launchpad: type: string nullable: true partnerConfig: type: string nullable: true graduatedPool: type: string nullable: true graduatedAt: type: string nullable: true holderCount: type: number nullable: true fdv: type: number nullable: true description: Fully diluted valuation in USD mcap: type: number nullable: true description: Market cap in USD usdPrice: type: number nullable: true priceBlockId: type: number nullable: true description: Solana block number for the price data point liquidity: type: number nullable: true description: Total liquidity in USD fees: type: number nullable: true description: Trading fees in USD apy: type: object nullable: true description: APY data, only present for assets listed on Jupiter Lend's Earn properties: jupEarn: type: number description: Annual percentage yield from Jupiter Earn stats5m: $ref: "#/components/schemas/SwapStats" nullable: true stats1h: $ref: "#/components/schemas/SwapStats" nullable: true stats6h: $ref: "#/components/schemas/SwapStats" nullable: true stats24h: $ref: "#/components/schemas/SwapStats" nullable: true stats7d: $ref: "#/components/schemas/SwapStats" nullable: true description: 7-day stats (typically only priceChange, but may include volume fields) stats30d: $ref: "#/components/schemas/SwapStats" nullable: true description: 30-day stats (typically only priceChange, but may include volume fields) firstPool: type: object nullable: true properties: id: type: string description: Pool address createdAt: type: string description: Pool creation timestamp audit: type: object nullable: true description: | Audit information. All sub-fields are conditional and vary per token. properties: isSus: type: boolean nullable: true description: | Flagged as suspicious. This field is only present when the token has been flagged — check for the field's presence, not its value. Not all risky tokens will have this flag. mintAuthorityDisabled: type: boolean nullable: true freezeAuthorityDisabled: type: boolean nullable: true topHoldersPercentage: type: number nullable: true description: Percentage of supply held by top holders devBalancePercentage: type: number nullable: true description: Percentage of supply held by the developer devMints: type: number nullable: true description: Number of developer mint events organicScore: type: number description: Organic trading activity score (0-100) organicScoreLabel: type: string enum: [high, medium, low] isVerified: type: boolean nullable: true tags: type: array items: type: string nullable: true updatedAt: type: string format: date-time description: Last data update timestamp SwapStats: type: object properties: priceChange: type: number nullable: true holderChange: type: number nullable: true liquidityChange: type: number nullable: true volumeChange: type: number nullable: true buyVolume: type: number nullable: true sellVolume: type: number nullable: true buyOrganicVolume: type: number nullable: true sellOrganicVolume: type: number nullable: true numBuys: type: number nullable: true numSells: type: number nullable: true numTraders: type: number nullable: true numOrganicBuyers: type: number nullable: true numNetBuyers: type: number nullable: true HoldingsResponse: type: object properties: amount: type: string description: Total SOL in lamports uiAmount: type: number description: Total SOL in UI units after applying decimals uiAmountString: type: string description: Total SOL as string in UI units after applying decimals tokens: type: object description: Other token holdings organized by mint address as keys additionalProperties: description: Token mint address as key type: array items: $ref: "#/components/schemas/TokenAccount" required: - amount - uiAmount - uiAmountString - tokens NativeHoldingsResponse: type: object properties: amount: type: string description: Total SOL in lamports uiAmount: type: number description: Total SOL in UI units after applying decimals uiAmountString: type: string description: Total SOL as string in UI units after applying decimals required: - amount - uiAmount - uiAmountString TokenAccount: type: object properties: account: type: string description: The token account address amount: type: string description: Token amount in atomic/raw units uiAmount: type: number description: Token amount in UI units after applying decimals uiAmountString: type: string description: Token amount as string in UI units after applying decimals isFrozen: type: boolean description: Whether the token account is frozen isAssociatedTokenAccount: type: boolean description: Whether this is an associated token account decimals: type: number description: Number of decimal places for the token programId: type: string description: The token program ID required: - account - amount - uiAmount - uiAmountString - isFrozen - isAssociatedTokenAccount - decimals - programId