{"openapi":"3.1.0","info":{"title":"Solana Concentrated Liquidity Deposit API","description":"API that builds Orca Whirlpool and Raydium CLMM deposit transactions for AI agents. The agent signs the returned transaction with its own wallet — no keys are ever held by this service.","version":"0.2.0"},"paths":{"/v1/pools/search":{"get":{"tags":["whirlpool"],"summary":"Search Pools","description":"List all pools for a token pair, sorted by TVL (highest first).\n\nUse **protocol=raydium** to search Raydium CLMM pools instead of Orca Whirlpools.","operationId":"search_pools_v1_pools_search_get","parameters":[{"name":"token_a","in":"query","required":true,"schema":{"type":"string","description":"Token A symbol, e.g. SOL","title":"Token A"},"description":"Token A symbol, e.g. SOL"},{"name":"token_b","in":"query","required":true,"schema":{"type":"string","description":"Token B symbol, e.g. USDC","title":"Token B"},"description":"Token B symbol, e.g. USDC"},{"name":"protocol","in":"query","required":false,"schema":{"type":"string","description":"Protocol: 'orca' or 'raydium'","default":"orca","title":"Protocol"},"description":"Protocol: 'orca' or 'raydium'"},{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PoolSearchResult"},"title":"Response Search Pools V1 Pools Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/pools/{pool_address}":{"get":{"tags":["whirlpool"],"summary":"Get Pool","description":"Fetch live on-chain state for a pool. Use protocol=raydium for Raydium CLMM pools.","operationId":"get_pool_v1_pools__pool_address__get","parameters":[{"name":"pool_address","in":"path","required":true,"schema":{"type":"string","title":"Pool Address"}},{"name":"protocol","in":"query","required":false,"schema":{"type":"string","description":"Protocol: 'orca' or 'raydium'","default":"orca","title":"Protocol"},"description":"Protocol: 'orca' or 'raydium'"},{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/position/{position_mint}":{"get":{"tags":["whirlpool"],"summary":"Get Position","description":"Fetch the current state of a liquidity position by its NFT mint address.\n\nUse **protocol=raydium** for Raydium CLMM positions.","operationId":"get_position_v1_position__position_mint__get","parameters":[{"name":"position_mint","in":"path","required":true,"schema":{"type":"string","title":"Position Mint"}},{"name":"protocol","in":"query","required":false,"schema":{"type":"string","description":"Protocol: 'orca' or 'raydium'","default":"orca","title":"Protocol"},"description":"Protocol: 'orca' or 'raydium'"},{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/withdraw":{"post":{"tags":["whirlpool"],"summary":"Withdraw","description":"Build a withdrawal transaction for an existing liquidity position.\n\nDecreases liquidity by **withdraw_percent** (default 100%), collects all\naccrued fees, and closes the position NFT when removing 100%.\nIf token A is wSOL the transaction also unwraps it back to native SOL.\n\nUse **protocol=raydium** for Raydium CLMM positions.\n\nThe returned transaction must be signed by the wallet and submitted to Solana.","operationId":"withdraw_v1_withdraw_post","parameters":[{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/quote":{"post":{"tags":["whirlpool"],"summary":"Get Quote","description":"Calculate liquidity and token amounts for a proposed deposit.\n\nUse **protocol=raydium** to quote for a Raydium CLMM pool.","operationId":"get_quote_v1_quote_post","parameters":[{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/transaction":{"post":{"tags":["whirlpool"],"summary":"Build Transaction","description":"Build a ready-to-sign deposit transaction from pre-calculated values.\n\nUse **protocol=raydium** to build a Raydium CLMM deposit transaction.\nOmit **position_mint** to open a new position; include it to add to an existing one.","operationId":"build_transaction_v1_transaction_post","parameters":[{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/deposit":{"post":{"tags":["whirlpool"],"summary":"Deposit","description":"One-shot deposit builder. Provide a token pair and an amount — the API\nhandles pool selection, price range, and transaction building automatically.\n\nUse **protocol=raydium** to deposit into a Raydium CLMM pool.\n\n**Examples:**\n- `{\"token_a\": \"SOL\", \"token_b\": \"USDC\", \"usd_amount\": 100, \"wallet_address\": \"...\", \"protocol\": \"orca\"}`\n- `{\"token_a\": \"SOL\", \"token_b\": \"USDC\", \"token_a_amount\": 1.5, \"wallet_address\": \"...\", \"protocol\": \"raydium\"}`","operationId":"deposit_v1_deposit_post","parameters":[{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"DepositRequest":{"properties":{"token_a":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token A","description":"Token A symbol, e.g. SOL"},"token_b":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token B","description":"Token B symbol, e.g. USDC"},"pool_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pool Address","description":"Specific pool address (overrides symbols)"},"protocol":{"type":"string","title":"Protocol","description":"Protocol: 'orca' or 'raydium'","default":"orca"},"wallet_address":{"type":"string","title":"Wallet Address"},"usd_amount":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Usd Amount","description":"Total USD value to deposit (requires a stablecoin in the pair)"},"token_a_amount":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Token A Amount","description":"Token A amount in human-readable units, e.g. 1.5 for 1.5 SOL"},"token_b_amount":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Token B Amount","description":"Token B amount in human-readable units, e.g. 100 for 100 USDC"},"range_percent":{"type":"number","exclusiveMinimum":0.0,"title":"Range Percent","description":"Price range ± % from current price (default: 10)","default":10.0},"slippage_bps":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Slippage Bps","default":50}},"type":"object","required":["wallet_address"],"title":"DepositRequest"},"DepositResponse":{"properties":{"transaction":{"type":"string","title":"Transaction"},"pool_address":{"type":"string","title":"Pool Address"},"position_mint":{"type":"string","title":"Position Mint"},"token_a_symbol":{"type":"string","title":"Token A Symbol"},"token_b_symbol":{"type":"string","title":"Token B Symbol"},"token_a_amount":{"type":"number","title":"Token A Amount"},"token_b_amount":{"type":"number","title":"Token B Amount"},"token_a_max":{"type":"number","title":"Token A Max"},"token_b_max":{"type":"number","title":"Token B Max"},"lower_price":{"type":"number","title":"Lower Price"},"upper_price":{"type":"number","title":"Upper Price"},"current_price":{"type":"number","title":"Current Price"},"message":{"type":"string","title":"Message"}},"type":"object","required":["transaction","pool_address","position_mint","token_a_symbol","token_b_symbol","token_a_amount","token_b_amount","token_a_max","token_b_max","lower_price","upper_price","current_price","message"],"title":"DepositResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PoolInfo":{"properties":{"address":{"type":"string","title":"Address"},"token_mint_a":{"type":"string","title":"Token Mint A"},"token_mint_b":{"type":"string","title":"Token Mint B"},"token_symbol_a":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Symbol A"},"token_symbol_b":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Symbol B"},"tick_spacing":{"type":"integer","title":"Tick Spacing"},"current_tick":{"type":"integer","title":"Current Tick"},"current_sqrt_price":{"type":"string","title":"Current Sqrt Price"},"liquidity":{"type":"string","title":"Liquidity"},"fee_rate":{"type":"integer","title":"Fee Rate"},"current_price":{"type":"number","title":"Current Price"},"tvl":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tvl"}},"type":"object","required":["address","token_mint_a","token_mint_b","tick_spacing","current_tick","current_sqrt_price","liquidity","fee_rate","current_price"],"title":"PoolInfo"},"PoolSearchResult":{"properties":{"address":{"type":"string","title":"Address"},"token_a_symbol":{"type":"string","title":"Token A Symbol"},"token_b_symbol":{"type":"string","title":"Token B Symbol"},"token_a_mint":{"type":"string","title":"Token A Mint"},"token_b_mint":{"type":"string","title":"Token B Mint"},"tick_spacing":{"type":"integer","title":"Tick Spacing"},"tvl":{"type":"number","title":"Tvl"},"fee_rate":{"type":"number","title":"Fee Rate"}},"type":"object","required":["address","token_a_symbol","token_b_symbol","token_a_mint","token_b_mint","tick_spacing","tvl","fee_rate"],"title":"PoolSearchResult"},"PositionInfo":{"properties":{"position_mint":{"type":"string","title":"Position Mint"},"pool_address":{"type":"string","title":"Pool Address"},"token_a_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token A Symbol"},"token_b_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token B Symbol"},"liquidity":{"type":"string","title":"Liquidity"},"tick_lower":{"type":"integer","title":"Tick Lower"},"tick_upper":{"type":"integer","title":"Tick Upper"},"lower_price":{"type":"number","title":"Lower Price"},"upper_price":{"type":"number","title":"Upper Price"},"current_price":{"type":"number","title":"Current Price"},"in_range":{"type":"boolean","title":"In Range"},"token_a_amount":{"type":"number","title":"Token A Amount"},"token_b_amount":{"type":"number","title":"Token B Amount"},"fee_owed_a":{"type":"number","title":"Fee Owed A"},"fee_owed_b":{"type":"number","title":"Fee Owed B"}},"type":"object","required":["position_mint","pool_address","liquidity","tick_lower","tick_upper","lower_price","upper_price","current_price","in_range","token_a_amount","token_b_amount","fee_owed_a","fee_owed_b"],"title":"PositionInfo"},"QuoteRequest":{"properties":{"pool_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pool Address","description":"Pool account address"},"token_a":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token A","description":"Token A symbol, e.g. SOL"},"token_b":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token B","description":"Token B symbol, e.g. USDC"},"protocol":{"type":"string","title":"Protocol","description":"Protocol: 'orca' or 'raydium'","default":"orca"},"lower_price":{"type":"number","exclusiveMinimum":0.0,"title":"Lower Price","description":"Lower bound price (token B per token A)"},"upper_price":{"type":"number","exclusiveMinimum":0.0,"title":"Upper Price","description":"Upper bound price (token B per token A)"},"token_a_amount":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Token A Amount","description":"Token A amount in base units"},"token_b_amount":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Token B Amount","description":"Token B amount in base units"},"slippage_bps":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Slippage Bps","description":"Slippage tolerance in bps","default":50}},"type":"object","required":["lower_price","upper_price"],"title":"QuoteRequest"},"QuoteResponse":{"properties":{"pool_address":{"type":"string","title":"Pool Address"},"token_a_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token A Symbol"},"token_b_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token B Symbol"},"liquidity":{"type":"string","title":"Liquidity"},"token_a_amount":{"type":"integer","title":"Token A Amount"},"token_b_amount":{"type":"integer","title":"Token B Amount"},"token_a_max":{"type":"integer","title":"Token A Max"},"token_b_max":{"type":"integer","title":"Token B Max"},"lower_tick":{"type":"integer","title":"Lower Tick"},"upper_tick":{"type":"integer","title":"Upper Tick"},"current_price":{"type":"number","title":"Current Price"},"current_tick":{"type":"integer","title":"Current Tick"}},"type":"object","required":["pool_address","liquidity","token_a_amount","token_b_amount","token_a_max","token_b_max","lower_tick","upper_tick","current_price","current_tick"],"title":"QuoteResponse"},"TransactionRequest":{"properties":{"pool_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pool Address","description":"Pool account address"},"token_a":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token A","description":"Token A symbol, e.g. SOL"},"token_b":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token B","description":"Token B symbol, e.g. USDC"},"protocol":{"type":"string","title":"Protocol","description":"Protocol: 'orca' or 'raydium'","default":"orca"},"wallet_address":{"type":"string","title":"Wallet Address"},"lower_tick":{"type":"integer","title":"Lower Tick"},"upper_tick":{"type":"integer","title":"Upper Tick"},"liquidity":{"type":"string","title":"Liquidity"},"token_a_max":{"type":"integer","title":"Token A Max"},"token_b_max":{"type":"integer","title":"Token B Max"},"position_mint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Position Mint","description":"Existing position mint address. Omit to open a new position."}},"type":"object","required":["wallet_address","lower_tick","upper_tick","liquidity","token_a_max","token_b_max"],"title":"TransactionRequest"},"TransactionResponse":{"properties":{"transaction":{"type":"string","title":"Transaction"},"pool_address":{"type":"string","title":"Pool Address"},"position_mint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Position Mint"},"message":{"type":"string","title":"Message"}},"type":"object","required":["transaction","pool_address","position_mint","message"],"title":"TransactionResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WithdrawRequest":{"properties":{"position_mint":{"type":"string","title":"Position Mint","description":"Position NFT mint address returned when the position was opened"},"wallet_address":{"type":"string","title":"Wallet Address"},"withdraw_percent":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Withdraw Percent","description":"Percentage of liquidity to remove (default: 100 = full withdrawal)","default":100.0},"slippage_bps":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Slippage Bps","default":50},"protocol":{"type":"string","title":"Protocol","description":"Protocol: 'orca' or 'raydium'","default":"orca"}},"type":"object","required":["position_mint","wallet_address"],"title":"WithdrawRequest"},"WithdrawResponse":{"properties":{"transaction":{"type":"string","title":"Transaction"},"position_mint":{"type":"string","title":"Position Mint"},"pool_address":{"type":"string","title":"Pool Address"},"token_a_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token A Symbol"},"token_b_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token B Symbol"},"liquidity_removed":{"type":"string","title":"Liquidity Removed"},"token_a_amount":{"type":"number","title":"Token A Amount"},"token_b_amount":{"type":"number","title":"Token B Amount"},"token_a_min":{"type":"number","title":"Token A Min"},"token_b_min":{"type":"number","title":"Token B Min"},"fee_owed_a":{"type":"number","title":"Fee Owed A"},"fee_owed_b":{"type":"number","title":"Fee Owed B"},"position_closed":{"type":"boolean","title":"Position Closed"},"message":{"type":"string","title":"Message"}},"type":"object","required":["transaction","position_mint","pool_address","liquidity_removed","token_a_amount","token_b_amount","token_a_min","token_b_min","fee_owed_a","fee_owed_b","position_closed","message"],"title":"WithdrawResponse"}}}}