# Saturn Saturn is a decentralized exchange (DEX) on the base layer of Bitcoin, introducing features that allow users to trade assets directly on Bitcoin without relying on custodial solutions, layer two bridges or wrapped assets. By utilizing the Arch Network's virtual machine and verifier nodes, Saturn enables smart contract functionalities, atomic swaps, and liquidity pools—bringing decentralized finance (DeFi) capabilities to Bitcoin's most secure base layer. *** #### About Saturn: A New Approach to Bitcoin DeFi * Overview: Saturn enables trading, liquidity provision, and decentralized finance on Bitcoin's main layer without bridging or wrapping assets. This feature provides a secure, transparent, and efficient trading experience while adhering to Bitcoin's principles. * Unique Value Proposition: Saturn simplifies DeFi on Bitcoin with an intuitive experience, making it comparable to trading experiences on networks like Solana while offering superior security through Bitcoin’s decentralization. #### History Saturn was born during the rise of the rare satoshi craze. The team noticed people trading Bitcoin derivatives, with pizza satoshis changing hands on Discord in an entirely trust-dependent environment—no reliable pricing or secure market structure existed. This created a highly inefficient market. Saturn’s first offering was a straightforward orderbook, allowing users to trade rare satoshi UTXOs securely. The product gained momentum as Bitcoin tokens became more popular, especially after the introduction of Runes. From the start, we’ve held a core belief: delivering the best possible user experience will drive the most growth on Bitcoin. This led to the development of Saturn’s second iteration, a trading wallet-based exchange on Bitcoin’s base layer, offering features like open orders, simple swaps, partially fillable orders, and mempool sniping resistance—functionality not available anywhere else. However, we recognized friction in the user experience with trading wallets, which fell short of our ideal. That’s when we partnered with Arch, whose smart contract execution on Bitcoin’s base layer enables us to bring an unparalleled DeFi experience directly to Bitcoin, creating a seamless and intuitive environment for our users. ## Important Links Saturn - \ \ Twitter - Discord -
# Trading in Saturn Trading Bitcoin tokens should be simple. That guiding principle has driven Saturn’s development from the very start, inspiring us to create a platform that removes the friction and complexity typically associated with trading on Bitcoin. Saturn is now the most seamless and reliable way to trade directly on Bitcoin’s base layer. It’s a powerful yet intuitive trading platform, built to deliver a smooth experience while maintaining Bitcoin’s trustless and decentralized nature. Saturn empowers users with advanced trading features, allowing for liquidity pools and AMM swaps on the base layer of Bitcoin. With Saturn’s latest enhancements, traders can engage with a streamlined UI, designed to offer easy access to deep liquidity and an unmatched DeFi experience on Bitcoin. # How to Swap 1. **Connect Wallet** - Click the "Connect" button
2. **Select Tokens** - Select the token you’d like to use (Sell) and the token you want to receive (Buy) using the dropdowns.
3. **Input Amounts** - Enter the amount you want to pay or receive in the appropriate fields, or use the "Half" or "Max" preset options to automatically fill in those specific values.
4. **Review Details** - A quote for your trade will be displayed below the "Submit" button, you can also use the "Show more" drop down arrow, to view more details about your trade.
5. **Submit** - Confirm the details of the trade, and if happy, click "Submit" and approve the transaction.\ \ The UI will display the progress of your trade before showing you a confirmation. # How Saturn Protects Your Trades from MEV Risks Maximal Extractable Value (MEV) can lead to unfair trading practices like front-running, where others profit by manipulating transactions. Saturn has implemented smart solutions to keep your trades safe and fair: 1. #### Secure BTC to Rune Swaps * Immutable Transactions: Your transactions are signed securely so they can't be changed once sent. * Your Benefit: Eliminates the risk of someone intercepting or altering your trade. 2. **Protected Rune to BTC Swaps** * Pooled Transactions with CPFP: Saturn pools user transactions and uses a method called Child Pays for Parent (CPFP), where each transaction supports the next. * Your Benefit: Makes it nearly impossible for attackers to interfere with your trade. 3. #### Transparent, User-Controlled Liquidity Pools * Non-Custodial Pools: You always maintain control of your funds. * Transparency: All operations are open, so you know exactly what's happening. * Your Benefit: No hidden manipulation—just fair and secure trading. 4. #### Fair Transaction Ordering * First-In, First-Out Processing: Transactions are processed exactly in the order they arrive. * Future Enhancements: Saturn is working on cryptographic methods to guarantee transaction order can't be tampered with. * Your Benefit: Ensures no one can jump the line or reorder trades to their advantage. # Open a position in a Liquidity Pool 1. **Navigate to the Pools section on the Saturn platform**
2. **Select the pool you want to open a position in** - In this example we will use BESTINSLOT.XYZ
3. **Select the pool for the token you have chosen with the fee rate that you desire**
4. **Click deposit to add to liquidity the pool**
5. **Enter the amounts** - Enter the liquidity amounts that you want to deposit into the pool. Review all pool details, including tokens, liquidity amounts, and fee tier.\ \ If this is a new pool and there is no liquidity, the amount of liquidity that you provide will set the initial price of the pool.\ \ *TIP: Ensure you double-check the token details to avoid creating a pool with the wrong assets.*
6. **Click Submit** - Submit and approve you transaction. Congratulations, you have added to liquidity to a pool!\ \ *NOTE: Creating a pool incurs network fees on the Bitcoin base layer. Review the fees before confirming.*
# Managing your Portfolio on Saturn 1. **Navigate to the portfolio tab which can be found in the "Pools" section of Saturn**
2. **Select the position you want to adjust**
If depositing, enter the liquidity amounts that you want to deposit into the pool. Review all pool details, including tokens, liquidity amounts, and fee tier. If this is a new pool and there is no liquidity, the amount of liquidity that you provide will set the initial price of the pool. *TIP: Ensure you double-check the token details to avoid creating a pool with the wrong assets.*
If withdrawing, enter the amount of tokens you wish to withdraw using the fields, percentage slider, or preset percentage buttons.
3. **Click Submit** - Once you have double checked all the detail are accurate, click the "Submit Button". Congratulations, you have successfully adjusted your position!
# How to Create a Pool on Saturn Creating a Pool on Saturn ### Introduction Creating a liquidity pool on Saturn allows you to bring your token into a decentralized, trustless trading environment directly on the Bitcoin base layer. Saturn pools eliminate the need for bridging or centralized intermediaries, offering a secure platform for Bitcoin-native token trading. ### Step-by-Step Guide to Creating a new Pool 1. **Navigate to the Pools Page** - Go to the Pools section on the Saturn platform.
2\. **Connect Your Wallet** - Ensure your wallet is connected and linked to the Bitcoin network.
3. **Create Pool** - Click the "Create Pool" button
4. **Select Pool Tokens** - Under "Token A" select the token you wish to create the pool for. Token B is automatically set as BTC.
5. **Select Fee Tier** - Fee tiers determine the trading fees that liquidity providers will earn. Choose a fee tier that aligns with your trading volume expectations. * **Low Fee Tier**: Ideal for high-volume tokens, offering a competitive trading fee. * **High Fee Tier**: Suited for less liquid tokens, allowing liquidity providers to earn more per trade.
6. **Submit** - Click the "Submit" button. Congratulations, you have just created a new liquidity pool for a Rune token!
# Saturn API Saturn has created the first decentralized AMM program on Bitcoin. To facilitate development on top of these liquidity pools, we've created APIs to make it easier for developers like you to build innovative applications. We offer two services: 1. [**Pool API**](/builders/saturn-api/pool-api): This API allows you to interact with the liquidity pools. You can create pools, open positions, add or remove liquidity, and perform token swaps. 2. [**Indexer API**](/builders/saturn-api/indexer-api): This service lets you search all available pools and provides extensive information and statistics about them. You can also view transactions made within a pool or by a user, filter by transaction type, and more. If you're eager to get started quickly, we've provided direct links to the Swagger documentation for each API, as well as a development environment powered by StockBlitz, so you can test these APIs directly. An API Key is required to call the different APIs. The best way to obtain an API Key is to reach out to us on [Telegram](https://t.me/+a7xuJQCamRdiYmQ0). If you feel like API is not your thing and you instead want to call the program on the Arch Network, check out our [Liquidity Pool SDK](/builders/liquidity-pool-sdk).
# Pool API The Pools API allows you to interact with the program's instructions for managing liquidity pools, performing swaps, and more. The general process for most instructions consists of three main steps: ### General Process Overview 1. **Generate a PSBT (Partially Signed Bitcoin Transaction):** * **Endpoint:** `/{instruction}/psbt` * **Description:** Call this endpoint to generate a PSBT along with additional information such as fees, inputs to sign, and other necessary data. * **Response Includes:** * The PSBT in base64 format. * Fee details. * Inputs that need to be signed. * Any additional necessary data. 2. **Obtain a Message to Sign:** * **Endpoint:** `/{instruction}/message` * **Description:** After generating and signing the PSBT, send it along with the required parameters for the instruction to this endpoint. It will return a message in hexadecimal format that you need to sign with your wallet. * **Requirements:** * Use **BIP322** for signing. * Use a **Taproot** address for the signature. 3. **Submit the Signed Message and Execute the Instruction:** * **Endpoint:** `/{instruction}` * **Description:** Once you have the signed message, send the signature along with the necessary parameters for the instruction to this endpoint. All parameters will be validated, and if everything matches, the message will be broadcast to the Arch network. #### Notes: * In some instructions, such as **Swap**, the signed PSBT is included in the message sent to the program. The program will then complete the PSBT with its relevant inputs and outputs and broadcast it to the network. * In other instructions, like **Increase Liquidity**, **Open Position**, **Initialize Pool**, and **Decrease Liquidity**, the PSBT is broadcast to the network in the third step, and immediately after, the program instruction is called. * The general process is similar across all instructions, but there are specific differences in some cases. ### Specific Instructions and Notes #### Decrease Liquidity * **Optional PSBT Creation:** Creating a PSBT is optional for this instruction. * **Purpose of PSBT:** The PSBT is used to pay transaction fees in case the BTC withdrawn from the pool is not sufficient to cover the network fees. * **Process:** If you choose to create a PSBT, follow the general process. If not, you can proceed directly to obtaining the message to sign. #### Swap from Rune to BTC * **Additional PSBT (`splitRunePsbt`):** When swapping from Rune to BTC, the `/{instruction}/psbt` endpoint may return an additional PSBT called `splitRunePsbt`. * **Purpose of `splitRunePsbt`:** This PSBT is necessary to create a transaction that generates a UTXO with the required amount of Runes to trade. * **Process:** * If the endpoint responds with a `splitRunePsbt`, you need to sign both the `splitRunePsbt` and the main PSBT for trading. * Send both signed PSBTs to the `/{instruction}/message` endpoint. ### Additional Considerations * **Signing Requirements:** * **BIP322:** Ensure you are using BIP322 for signing messages. This standard allows for message signing in a way that is compatible with Bitcoin's consensus rules. * **Taproot Addresses:** Signatures for Arch Network messages must come from a Taproot address. ### Start building now If you want to get a hands-on experience now and stop reading docs, check out these options and start building with the Pools API: * [**Typescript SDK**](https://www.npmjs.com/package/@saturnbtcio/pools-api-sdk): A fully-featured SDK, allowing for easy and type-safe interactions with the API. * [**Swagger Documentation**](https://api.staging.saturnbtc.io/swagger): An OpenAPI specification is available, providing detailed information about each endpoint, request, and response format. * [**Stackblitz Environment**](https://saturnbtc.io/sdk/api): We've deployed a Stockblitz environment where you can experiment with the API in a live setting, enabling you to test queries and see real-time data without setting up your own backend. # Initialize pool ## Initialize Pool PSBT > Generates a partially signed Bitcoin transaction (PSBT) for creating the needed UTXOs for creating the accounts\ > for a pool.\ > \ > The request body containing details for creating accounts PSBT. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Pool"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"InitPoolCreateAccountsPsbtRequestIApiRequest":{"type":"object","properties":{"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"shardsLength":{"type":"number","title":"The number of accounts to create. Maximum is 10","description":"The number of accounts to create. Maximum is 10."},"token0":{"type":"string","title":"The first token's identifier","description":"The first token's identifier."},"token1":{"type":"string","title":"The second token's identifier","description":"The second token's identifier."},"feeTier":{"type":"number","title":"The fee tier for the pool","description":"The fee tier for the pool."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["feeRate","shardsLength","token0","token1","feeTier","runePubkey","runeAddress"]},"PsbtResponse":{"type":"object","properties":{"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"UtxoToSign":{"type":"object","properties":{"address":{"type":"string","description":"Address that should sign the transaction"},"signingIndexes":{"type":"array","items":{"type":"number"},"description":"Indexes of the inputs to sign"},"sigHash":{"type":"number","description":"Sig hash type"},"utxo":{"type":"string","title":"Utxo id (txid:vout) of the utxo used in the psbt","description":"Utxo id (txid:vout) of the utxo used in the psbt."}},"required":["address","signingIndexes","utxo"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/initialize-pool/psbt":{"post":{"summary":"Initialize Pool PSBT","description":"Generates a partially signed Bitcoin transaction (PSBT) for creating the needed UTXOs for creating the accounts\nfor a pool.\n\nThe request body containing details for creating accounts PSBT.","tags":["Pool"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitPoolCreateAccountsPsbtRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"An object containing the PSBT, fee, utxos to sign, and the created accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PsbtResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Initialize Pool Message > Generates a message hash required to initialize a pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Pool"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"InitializePoolMessageRequestIApiRequest":{"type":"object","properties":{"token0":{"type":"string","title":"The first token's identifier","description":"The first token's identifier."},"token1":{"type":"string","title":"The second token's identifier","description":"The second token's identifier."},"feeTier":{"type":"number","title":"The fee tier for the pool","description":"The fee tier for the pool."},"shardsLength":{"type":"number","title":"The number of accounts to create. Maximum is 5","description":"The number of accounts to create. Maximum is 5."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["token0","token1","feeTier","shardsLength","recentBlockhash","feeRate","signedPsbt","runePubkey","runeAddress"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/initialize-pool/message":{"post":{"summary":"Initialize Pool Message","description":"Generates a message hash required to initialize a pool.","tags":["Pool"],"parameters":[],"requestBody":{"description":"The request body containing pool initialization details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializePoolMessageRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"A hexadecimal string representing the hash of the initialization message.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Initialize Pool > Finalizes the pool initialization process. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Pool"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"InitializePoolRequestIApiRequest":{"type":"object","properties":{"signature":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The user's signature of the initialization message","description":"The user's signature of the initialization message."},"token0":{"type":"string","title":"The first token's identifier","description":"The first token's identifier."},"token1":{"type":"string","title":"The second token's identifier","description":"The second token's identifier."},"feeTier":{"type":"number","title":"The fee tier for the pool","description":"The fee tier for the pool."},"shardsLength":{"type":"number","title":"The number of accounts to create. Maximum is 5","description":"The number of accounts to create. Maximum is 5."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signature","token0","token1","feeTier","shardsLength","recentBlockhash","feeRate","signedPsbt","runePubkey","runeAddress"]},"InstructionResponse":{"type":"object","properties":{"archTxId":{"type":"string","title":"Transaction id of the transaction in Arch","description":"Transaction id of the transaction in Arch."},"bitcoinTxIds":{"type":"array","items":{"type":"string"},"description":"Some bitcoin transactions ids that we have broadcasted. The Arch Network will\nsubmit a new bitcoin transaction after these ones."}},"required":["archTxId","bitcoinTxIds"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/initialize-pool":{"post":{"summary":"Initialize Pool","description":"Finalizes the pool initialization process.","tags":["Pool"],"parameters":[],"requestBody":{"description":"The request body containing the initialization request and signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializePoolRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"The Arch Network transaction ID of the pool creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` # Add Shards ## Add Pool Shards PSBT > Generates a PSBT for adding shards to an existing pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Pool"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"AddShardsCreateAccountsPsbtRequestIApiRequest":{"type":"object","properties":{"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"shardsLength":{"type":"number","title":"The number of accounts to create. Maximum is 10","description":"The number of accounts to create. Maximum is 10."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The id of the pool to add shards","description":"The id of the pool to add shards."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["feeRate","shardsLength","poolId","runePubkey","runeAddress"]},"PsbtResponse":{"type":"object","properties":{"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"UtxoToSign":{"type":"object","properties":{"address":{"type":"string","description":"Address that should sign the transaction"},"signingIndexes":{"type":"array","items":{"type":"number"},"description":"Indexes of the inputs to sign"},"sigHash":{"type":"number","description":"Sig hash type"},"utxo":{"type":"string","title":"Utxo id (txid:vout) of the utxo used in the psbt","description":"Utxo id (txid:vout) of the utxo used in the psbt."}},"required":["address","signingIndexes","utxo"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/add-pool-shards/psbt":{"post":{"summary":"Add Pool Shards PSBT","description":"Generates a PSBT for adding shards to an existing pool.","tags":["Pool"],"parameters":[],"requestBody":{"description":"The request body containing details for creating accounts PSBT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddShardsCreateAccountsPsbtRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"An object containing the PSBT, fee, utxos to sign, and the created accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PsbtResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Add Pool Shards Message > Generates a message hash required to add shards to a pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Pool"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"AddPoolShardsMessageRequestIApiRequest":{"type":"object","properties":{"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"shardsLength":{"type":"number","title":"The number of accounts to create. Maximum is 10","description":"The number of accounts to create. Maximum is 10."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["poolId","feeRate","signedPsbt","shardsLength","recentBlockhash","runePubkey","runeAddress"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/add-pool-shards/message":{"post":{"summary":"Add Pool Shards Message","description":"Generates a message hash required to add shards to a pool.","tags":["Pool"],"parameters":[],"requestBody":{"description":"The request body containing details for adding pool shards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPoolShardsMessageRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"A hexadecimal string representing the hash of the add shards message.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Add Pool Shards > Finalizes the process of adding shards to a pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Pool"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"AddPoolShardsRequestIApiRequest":{"type":"object","properties":{"signature":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The user's signature of the initialization message","description":"The user's signature of the initialization message."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"shardsLength":{"type":"number","title":"The number of accounts to create. Maximum is 10","description":"The number of accounts to create. Maximum is 10."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signature","poolId","feeRate","signedPsbt","shardsLength","recentBlockhash","runePubkey","runeAddress"]},"InstructionResponse":{"type":"object","properties":{"archTxId":{"type":"string","title":"Transaction id of the transaction in Arch","description":"Transaction id of the transaction in Arch."},"bitcoinTxIds":{"type":"array","items":{"type":"string"},"description":"Some bitcoin transactions ids that we have broadcasted. The Arch Network will\nsubmit a new bitcoin transaction after these ones."}},"required":["archTxId","bitcoinTxIds"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/add-pool-shards":{"post":{"summary":"Add Pool Shards","description":"Finalizes the process of adding shards to a pool.","tags":["Pool"],"parameters":[],"requestBody":{"description":"The request body containing the add shards request and signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPoolShardsRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"The Arch Network transaction ID of the pool shards addition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` # Open position ## Open Position PSBT > Generates a PSBT for opening a new liquidity position by sending funds to the pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"SendFundsPsbtRequestIApiRequest":{"type":"object","properties":{"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pool's identifier","description":"The pool's identifier."},"amount0":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the first token to deposit","description":"The amount of the first token to deposit."},"amount1":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the second token to deposit","description":"The amount of the second token to deposit."},"initializeAccountUtxo":{"type":"boolean","title":"A boolean indicating whether to initialize the account UTXO","description":"A boolean indicating whether to initialize the account UTXO.\nIf you're creating a new position, you should set this to `true`."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["poolId","amount0","amount1","initializeAccountUtxo","feeRate","runePubkey","runeAddress"]},"SendFundsPsbtResponse":{"type":"object","properties":{"mergeUtxoPsbt":{"$ref":"#/components/schemas/PsbtResponse"},"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"PsbtResponse":{"type":"object","properties":{"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"UtxoToSign":{"type":"object","properties":{"address":{"type":"string","description":"Address that should sign the transaction"},"signingIndexes":{"type":"array","items":{"type":"number"},"description":"Indexes of the inputs to sign"},"sigHash":{"type":"number","description":"Sig hash type"},"utxo":{"type":"string","title":"Utxo id (txid:vout) of the utxo used in the psbt","description":"Utxo id (txid:vout) of the utxo used in the psbt."}},"required":["address","signingIndexes","utxo"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/open-position/psbt":{"post":{"summary":"Open Position PSBT","description":"Generates a PSBT for opening a new liquidity position by sending funds to the pool.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the funding details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendFundsPsbtRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"An object containing the PSBT (in base64 format), the fee, the list of UTXOs to sign, and optionally the created account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendFundsPsbtResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Open Position Message > Generates a message hash for opening a new liquidity position, which the user should sign. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"OpenPositionMessageRequestIApiRequest":{"type":"object","properties":{"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the pool","description":"The pubkey of the pool."},"amount0":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the first token to deposit","description":"The amount of the first token to deposit."},"amount1":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the second token to deposit","description":"The amount of the second token to deposit."},"maxAmount0":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the first token to deposit","description":"The maximum amount of the first token to deposit."},"maxAmount1":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the second token to deposit","description":"The maximum amount of the second token to deposit."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"mergeUtxoPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The merge UTXO PSBT in base64 format","description":"The merge UTXO PSBT in base64 format."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["poolId","amount0","amount1","maxAmount0","maxAmount1","feeRate","signedPsbt","recentBlockhash","runePubkey","runeAddress"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/open-position/message":{"post":{"summary":"Open Position Message","description":"Generates a message hash for opening a new liquidity position, which the user should sign.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the position opening details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenPositionMessageRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"A hexadecimal string representing the hash of the message to be signed by the user.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Open Position > Finalizes the opening of a new liquidity position by submitting the signed message and executing the transaction on the network. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"OpenPositionRequestIApiRequest":{"type":"object","properties":{"signature":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The user's signature of the open position message","description":"The user's signature of the open position message."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the pool","description":"The pubkey of the pool."},"amount0":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the first token to deposit","description":"The amount of the first token to deposit."},"amount1":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the second token to deposit","description":"The amount of the second token to deposit."},"maxAmount0":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the first token to deposit","description":"The maximum amount of the first token to deposit."},"maxAmount1":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the second token to deposit","description":"The maximum amount of the second token to deposit."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"mergeUtxoPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The merge UTXO PSBT in base64 format","description":"The merge UTXO PSBT in base64 format."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signature","poolId","amount0","amount1","maxAmount0","maxAmount1","feeRate","signedPsbt","recentBlockhash","runePubkey","runeAddress"]},"InstructionResponse":{"type":"object","properties":{"archTxId":{"type":"string","title":"Transaction id of the transaction in Arch","description":"Transaction id of the transaction in Arch."},"bitcoinTxIds":{"type":"array","items":{"type":"string"},"description":"Some bitcoin transactions ids that we have broadcasted. The Arch Network will\nsubmit a new bitcoin transaction after these ones."}},"required":["archTxId","bitcoinTxIds"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/open-position":{"post":{"summary":"Open Position","description":"Finalizes the opening of a new liquidity position by submitting the signed message and executing the transaction on the network.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the position opening request and signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenPositionRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"The Arch Network transaction ID of the position opening.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` # Increase Liquidity ## Increase Liquidity PSBT > Generates a PSBT for increasing liquidity in an existing position by sending funds to the pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"SendFundsPsbtRequestIApiRequest":{"type":"object","properties":{"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pool's identifier","description":"The pool's identifier."},"amount0":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the first token to deposit","description":"The amount of the first token to deposit."},"amount1":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the second token to deposit","description":"The amount of the second token to deposit."},"initializeAccountUtxo":{"type":"boolean","title":"A boolean indicating whether to initialize the account UTXO","description":"A boolean indicating whether to initialize the account UTXO.\nIf you're creating a new position, you should set this to `true`."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["poolId","amount0","amount1","initializeAccountUtxo","feeRate","runePubkey","runeAddress"]},"SendFundsPsbtResponse":{"type":"object","properties":{"mergeUtxoPsbt":{"$ref":"#/components/schemas/PsbtResponse"},"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"PsbtResponse":{"type":"object","properties":{"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"UtxoToSign":{"type":"object","properties":{"address":{"type":"string","description":"Address that should sign the transaction"},"signingIndexes":{"type":"array","items":{"type":"number"},"description":"Indexes of the inputs to sign"},"sigHash":{"type":"number","description":"Sig hash type"},"utxo":{"type":"string","title":"Utxo id (txid:vout) of the utxo used in the psbt","description":"Utxo id (txid:vout) of the utxo used in the psbt."}},"required":["address","signingIndexes","utxo"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/increase-liquidity/psbt":{"post":{"summary":"Increase Liquidity PSBT","description":"Generates a PSBT for increasing liquidity in an existing position by sending funds to the pool.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the funding details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendFundsPsbtRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"An object containing the PSBT (in base64 format), the fee, and the list of UTXOs to sign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendFundsPsbtResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Increase Liquidity Message > Generates a message hash for increasing liquidity in an existing position, which the user should sign. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"IncreaseLiquidityMessageRequestIApiRequest":{"type":"object","properties":{"positionPubKey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the position","description":"The pubkey of the position."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the pool","description":"The pubkey of the pool."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"mergeUtxoPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The merge UTXO PSBT in base64 format","description":"The merge UTXO PSBT in base64 format."},"amount0":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the first token to deposit","description":"The amount of the first token to deposit."},"amount1":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the second token to deposit","description":"The amount of the second token to deposit."},"maxAmount0":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the first token to deposit","description":"The maximum amount of the first token to deposit."},"maxAmount1":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the second token to deposit","description":"The maximum amount of the second token to deposit."},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["positionPubKey","poolId","feeRate","signedPsbt","recentBlockhash","runePubkey","amount0","amount1","maxAmount0","maxAmount1","runeAddress"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/increase-liquidity/message":{"post":{"summary":"Increase Liquidity Message","description":"Generates a message hash for increasing liquidity in an existing position, which the user should sign.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the liquidity increase details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncreaseLiquidityMessageRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"A hexadecimal string representing the hash of the message to be signed by the user.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Increase Liquidity > Finalizes the increase of liquidity in an existing position by submitting the signed message and executing the transaction on the network. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"IncreaseLiquidityRequestIApiRequest":{"type":"object","properties":{"signature":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The user's signature of the increase liquidity message","description":"The user's signature of the increase liquidity message."},"positionPubKey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the position","description":"The pubkey of the position."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the pool","description":"The pubkey of the pool."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"mergeUtxoPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The merge UTXO PSBT in base64 format","description":"The merge UTXO PSBT in base64 format."},"amount0":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the first token to deposit","description":"The amount of the first token to deposit."},"amount1":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of the second token to deposit","description":"The amount of the second token to deposit."},"maxAmount0":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the first token to deposit","description":"The maximum amount of the first token to deposit."},"maxAmount1":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The maximum amount of the second token to deposit","description":"The maximum amount of the second token to deposit."},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signature","positionPubKey","poolId","feeRate","signedPsbt","recentBlockhash","runePubkey","amount0","amount1","maxAmount0","maxAmount1","runeAddress"]},"InstructionResponse":{"type":"object","properties":{"archTxId":{"type":"string","title":"Transaction id of the transaction in Arch","description":"Transaction id of the transaction in Arch."},"bitcoinTxIds":{"type":"array","items":{"type":"string"},"description":"Some bitcoin transactions ids that we have broadcasted. The Arch Network will\nsubmit a new bitcoin transaction after these ones."}},"required":["archTxId","bitcoinTxIds"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/increase-liquidity":{"post":{"summary":"Increase Liquidity","description":"Finalizes the increase of liquidity in an existing position by submitting the signed message and executing the transaction on the network.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the liquidity increase request and signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncreaseLiquidityRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"The Arch Network transaction ID of the liquidity increase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` # Remove Liquidity ## Decrease Liquidity Message > Generates a message hash for decreasing liquidity from a position, which the user should sign. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"BasicDecreaseLiquidityRequestUserInforecentBlockhashstringpaymentMethodDecreaseLiquidityPaymentMethodIApiRequest":{"type":"object","properties":{"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the pool","description":"The pubkey of the pool."},"positionPubKey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the position","description":"The pubkey of the position."},"liquidityAmount":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of liquidity to withdraw","description":"The amount of liquidity to withdraw."},"minToken0":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The minimum amount of the first token to withdraw","description":"The minimum amount of the first token to withdraw."},"minToken1":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The minimum amount of the second token to withdraw","description":"The minimum amount of the second token to withdraw."},"withdrawAddressToken0":{"type":"string","title":"The address to withdraw the first token to","description":"The address to withdraw the first token to."},"withdrawAddressToken1":{"type":"string","title":"The address to withdraw the second token to","description":"The address to withdraw the second token to."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"paymentMethod":{"oneOf":[{"type":"object","properties":{"type":{"const":"fee_utxo"},"feeUtxo":{"$ref":"#/components/schemas/UtxoMetaData"}},"required":["type","feeUtxo"]},{"type":"object","properties":{"type":{"const":"signed_psbt"},"signedPsbt":{"type":"string"}},"required":["type","signedPsbt"]},{"type":"object","properties":{"type":{"const":"none"}},"required":["type"]}],"title":"The payment method for transaction fees","description":"The payment method for transaction fees."},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["poolId","positionPubKey","liquidityAmount","minToken0","minToken1","withdrawAddressToken0","withdrawAddressToken1","feeRate","runePubkey","recentBlockhash","paymentMethod","runeAddress"]},"UtxoMetaData":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"}},"required":["txid","vout"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/decrease-liquidity/message":{"post":{"summary":"Decrease Liquidity Message","description":"Generates a message hash for decreasing liquidity from a position, which the user should sign.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the liquidity decrease details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicDecreaseLiquidityRequestUserInforecentBlockhashstringpaymentMethodDecreaseLiquidityPaymentMethodIApiRequest"}}},"required":true},"responses":{"201":{"description":"A hexadecimal string representing the hash of the message to be signed by the user.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Decrease Liquidity > Finalizes the decrease of liquidity from a position by submitting the signed message and executing the transaction on the network. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Liquidity"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"DecreaseLiquidityRequestIApiRequest":{"type":"object","properties":{"signature":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The user's signature of the decrease liquidity message","description":"The user's signature of the decrease liquidity message."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the pool","description":"The pubkey of the pool."},"positionPubKey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The pubkey of the position","description":"The pubkey of the position."},"liquidityAmount":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of liquidity to withdraw","description":"The amount of liquidity to withdraw."},"minToken0":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The minimum amount of the first token to withdraw","description":"The minimum amount of the first token to withdraw."},"minToken1":{"type":"string","pattern":"^[0-9][0-9]*$","title":"The minimum amount of the second token to withdraw","description":"The minimum amount of the second token to withdraw."},"withdrawAddressToken0":{"type":"string","title":"The address to withdraw the first token to","description":"The address to withdraw the first token to."},"withdrawAddressToken1":{"type":"string","title":"The address to withdraw the second token to","description":"The address to withdraw the second token to."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"paymentMethod":{"oneOf":[{"type":"object","properties":{"type":{"const":"fee_utxo"},"feeUtxo":{"$ref":"#/components/schemas/UtxoMetaData"}},"required":["type","feeUtxo"]},{"type":"object","properties":{"type":{"const":"signed_psbt"},"signedPsbt":{"type":"string"}},"required":["type","signedPsbt"]},{"type":"object","properties":{"type":{"const":"none"}},"required":["type"]}],"title":"The payment method for transaction fees","description":"The payment method for transaction fees."},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signature","poolId","positionPubKey","liquidityAmount","minToken0","minToken1","withdrawAddressToken0","withdrawAddressToken1","feeRate","runePubkey","recentBlockhash","paymentMethod","runeAddress"]},"UtxoMetaData":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"}},"required":["txid","vout"]},"InstructionResponse":{"type":"object","properties":{"archTxId":{"type":"string","title":"Transaction id of the transaction in Arch","description":"Transaction id of the transaction in Arch."},"bitcoinTxIds":{"type":"array","items":{"type":"string"},"description":"Some bitcoin transactions ids that we have broadcasted. The Arch Network will\nsubmit a new bitcoin transaction after these ones."}},"required":["archTxId","bitcoinTxIds"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/decrease-liquidity":{"post":{"summary":"Decrease Liquidity","description":"Finalizes the decrease of liquidity from a position by submitting the signed message and executing the transaction on the network.","tags":["Liquidity"],"parameters":[],"requestBody":{"description":"The request body containing the liquidity decrease request and signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecreaseLiquidityRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"The Arch Network transaction ID of the liquidity decrease.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` # Swap ## Swap PSBT > Generates a PSBT for performing a swap between tokens in a pool. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Swap"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"SwapInfoUserInfoIApiRequest":{"type":"object","properties":{"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The identifier of the pool","description":"The identifier of the pool."},"amountIn":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of input token to swap","description":"The amount of input token to swap."},"amountOut":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of output token expected","description":"The amount of output token expected."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"zeroToOne":{"type":"boolean","title":"A boolean indicating whether to swap from token0 to token1","description":"A boolean indicating whether to swap from token0 to token1."},"exactIn":{"type":"boolean","title":"A boolean indicating whether the swap is exact in","description":"A boolean indicating whether the swap is exact in."},"splitRunePsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The split rune PSBT in base64 format","description":"The split rune PSBT in base64 format."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["poolId","amountIn","amountOut","feeRate","zeroToOne","exactIn","runePubkey","runeAddress"]},"SwapPsbtResponse":{"type":"object","properties":{"splitRunePsbt":{"$ref":"#/components/schemas/SplitRunePsbtResponse","description":"Split rune psbt response. This is only needed in the RUNE=>BTC swap if we haven't found\na utxo with all the RUNE tokens we want."},"mergeUtxoPsbt":{"$ref":"#/components/schemas/PsbtResponse","title":"Merge UTXO psbt response. This is only needed in the BTC=>RUNE swap when inputs must be consolidated","description":"Merge UTXO psbt response. This is only needed in the BTC=>RUNE swap when inputs must be consolidated."},"shardPubkeys":{"type":"array","items":{"type":"string"},"title":"Shard pubkeys. This is only needed in the BTC=>RUNE swap","description":"Shard pubkeys. This is only needed in the BTC=>RUNE swap."},"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"SplitRunePsbtResponse":{"type":"object","properties":{"totalAmount":{"type":"string","title":"Total amount of RUNE in the utxo(s) we are splitting","description":"Total amount of RUNE in the utxo(s) we are splitting."},"amountToReceive":{"type":"string","title":"Amount of RUNE we will receive in the output for placing the swpa order","description":"Amount of RUNE we will receive in the output for placing the swpa order."},"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["totalAmount","amountToReceive","psbt","fee","utxosToSign"]},"UtxoToSign":{"type":"object","properties":{"address":{"type":"string","description":"Address that should sign the transaction"},"signingIndexes":{"type":"array","items":{"type":"number"},"description":"Indexes of the inputs to sign"},"sigHash":{"type":"number","description":"Sig hash type"},"utxo":{"type":"string","title":"Utxo id (txid:vout) of the utxo used in the psbt","description":"Utxo id (txid:vout) of the utxo used in the psbt."}},"required":["address","signingIndexes","utxo"]},"PsbtResponse":{"type":"object","properties":{"psbt":{"type":"string","description":"Psbt base64 encoded to sign"},"fee":{"type":"number","description":"Raw fees in satoshis of the transaction"},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/UtxoToSign"},"description":"Inputs to sign"}},"required":["psbt","fee","utxosToSign"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/swap/psbt":{"post":{"summary":"Swap PSBT","description":"Generates a PSBT for performing a swap between tokens in a pool.","tags":["Swap"],"parameters":[],"requestBody":{"description":"The request body containing the swap details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapInfoUserInfoIApiRequest"}}},"required":true},"responses":{"201":{"description":"An object containing the PSBT (in base64 format), the fee, the list of UTXOs to sign, and optionally additional swap details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapPsbtResponse"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Swap Message > Generates a message hash for performing a swap, which the user should sign. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Swap"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"SwapMessageRequestIApiRequest":{"type":"object","properties":{"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"splitRunePsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The split rune PSBT in base64 format","description":"The split rune PSBT in base64 format."},"mergeUtxoPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The merge UTXO PSBT in base64 format","description":"The merge UTXO PSBT in base64 format."},"shardPubkeys":{"type":"array","items":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66},"description":"The pubkeys of the shards. Only applicable in the btc=>rune swap. (zeroToOne=false)"},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The identifier of the pool","description":"The identifier of the pool."},"amountIn":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of input token to swap","description":"The amount of input token to swap."},"amountOut":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of output token expected","description":"The amount of output token expected."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"zeroToOne":{"type":"boolean","title":"A boolean indicating whether to swap from token0 to token1","description":"A boolean indicating whether to swap from token0 to token1."},"exactIn":{"type":"boolean","title":"A boolean indicating whether the swap is exact in","description":"A boolean indicating whether the swap is exact in."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signedPsbt","recentBlockhash","poolId","amountIn","amountOut","feeRate","zeroToOne","exactIn","runePubkey","runeAddress"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/swap/message":{"post":{"summary":"Swap Message","description":"Generates a message hash for performing a swap, which the user should sign.","tags":["Swap"],"parameters":[],"requestBody":{"description":"The request body containing the swap details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapMessageRequestIApiRequest"}}},"required":true},"responses":{"201":{"description":"A hexadecimal string representing the hash of the message to be signed by the user.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Swap > Finalizes the swap transaction by submitting the signed message and executing the swap on the network. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Swap"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"SwapMessageRequestsignatureBase64StringIApiRequest":{"type":"object","properties":{"signedPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The signed PSBT in base64 format","description":"The signed PSBT in base64 format."},"splitRunePsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The split rune PSBT in base64 format","description":"The split rune PSBT in base64 format."},"mergeUtxoPsbt":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The merge UTXO PSBT in base64 format","description":"The merge UTXO PSBT in base64 format."},"shardPubkeys":{"type":"array","items":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66},"description":"The pubkeys of the shards. Only applicable in the btc=>rune swap. (zeroToOne=false)"},"recentBlockhash":{"type":"string","title":"The recent blockhash of the transaction","description":"The recent blockhash of the transaction."},"poolId":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The identifier of the pool","description":"The identifier of the pool."},"amountIn":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of input token to swap","description":"The amount of input token to swap."},"amountOut":{"type":"string","pattern":"^[1-9][0-9]*$","title":"The amount of output token expected","description":"The amount of output token expected."},"feeRate":{"type":"integer","minimum":1,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},"zeroToOne":{"type":"boolean","title":"A boolean indicating whether to swap from token0 to token1","description":"A boolean indicating whether to swap from token0 to token1."},"exactIn":{"type":"boolean","title":"A boolean indicating whether the swap is exact in","description":"A boolean indicating whether the swap is exact in."},"runePubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the rune address of the user initiating the request","description":"The public key of the rune address of the user initiating the request."},"paymentPubkey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The public key of the bitcoin address of the user initiating the request","description":"The public key of the bitcoin address of the user initiating the request.\nIf the user doesn't have a bitcoin address, the runePubkey will be used"},"signature":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$","title":"The user's signature of the swap message","description":"The user's signature of the swap message."},"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."}},"required":["signedPsbt","recentBlockhash","poolId","amountIn","amountOut","feeRate","zeroToOne","exactIn","runePubkey","signature","runeAddress"]},"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}},"paths":{"/v0/pool/swap":{"post":{"summary":"Swap","description":"Finalizes the swap transaction by submitting the signed message and executing the swap on the network.","tags":["Swap"],"parameters":[],"requestBody":{"description":"The request body containing the swap request and signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapMessageRequestsignatureBase64StringIApiRequest"}}},"required":true},"responses":{"201":{"description":"The Arch Network transaction ID of the swap.","content":{"application/json":{"schema":{"type":"object","properties":{"archTxId":{"type":"string"},"bitcoinTxIds":{"type":"array","items":{"type":"string"}}},"required":["archTxId","bitcoinTxIds"]}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ### How to Apply Slippage to Your Swaps * **Understanding Slippage:** Slippage refers to the difference between the expected price of a trade and the price at which the trade is executed. * **Applying Slippage:** * To apply slippage, request less `amountOut` for the `amountIn` you are swapping. * For example, to apply a 3% slippage tolerance: * Subtract 3% from the `amountOut` value. * Use this adjusted `amountOut` in your swap request. #### Swap Processing: * **Program Behavior:** * The program checks if you are entitled to receive more `tokenOut` than specified in the transaction. * **If Yes:** * **Swap from Rune to BTC:** The program will include the additional BTC you should receive in the transaction. * **Swap from BTC to Rune:** The program will hold the extra Rune you should have received. In your next call to the program, it will send you your corresponding portion. # Swap Quotes ### Swap Details Endpoint * **Endpoint:** `/swap/details` * **Description:** This endpoint allows you to obtain the best exchange rate between two tokens and identify the best pool to perform the swap. * **Response Includes:** * Best pool for performing the swap. * `amountIn` and `amountOut` values. * Network fees and liquidity provider fees. * Price impact of the swap. #### Important Notes: * **Swap from Rune to BTC:** * The `amountOut` provided by the `/swap/details` endpoint does not account for the network fees. * You need to subtract the network fees from the `amountOut` to get the correct amount to send to the endpoint. ## Get Swap Details > Retrieves detailed information about a potential swap, including expected amounts and fees. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Swap"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"paths":{"/v0/pool/swap/details":{"get":{"summary":"Get Swap Details","description":"Retrieves detailed information about a potential swap, including expected amounts and fees.","tags":["Swap"],"parameters":[{"name":"feeRate","in":"query","schema":{"type":"integer","minimum":1},"required":true,"title":"The fee rate for the transaction (in sats per byte)","description":"The fee rate for the transaction (in sats per byte)."},{"name":"token0","in":"query","schema":{"type":"string"},"required":true,"description":"The identifier of the first token. Format: `0:0`"},{"name":"token1","in":"query","schema":{"type":"string"},"required":true,"description":"The identifier of the second token. Usually '0:0: (Bitcoin)"},{"name":"zeroToOne","in":"query","schema":{"type":"boolean"},"required":true,"title":"A boolean indicating whether to swap from token0 to token1","description":"A boolean indicating whether to swap from token0 to token1."},{"name":"exactIn","in":"query","schema":{"type":"boolean"},"required":true,"title":"A boolean indicating whether the swap is exact in","description":"A boolean indicating whether the swap is exact in."},{"name":"amount","in":"query","schema":{"type":"string","pattern":"^[1-9][0-9]*$"},"required":true}],"responses":{"200":{"description":"An object containing detailed swap information such as expected amounts, price, price impact, fees, and pool ID.","content":{"application/json":{"schema":{"type":"object","properties":{"amountIn":{"type":"string","title":"The amount of input token to swap","description":"The amount of input token to swap."},"amountOut":{"type":"string","title":"The amount of output token expected","description":"The amount of output token expected."},"price":{"type":"string","title":"The price of the swap","description":"The price of the swap."},"priceImpact":{"type":"string","title":"The price impact of the swap","description":"The price impact of the swap."},"fees":{"type":"object","properties":{"makers":{"type":"string","title":"The fee paid to the makers","description":"The fee paid to the makers."},"network":{"type":"string","title":"The fee paid to the network","description":"The fee paid to the network."}},"required":["makers","network"],"title":"The fees paid for the swap","description":"The fees paid for the swap."},"poolId":{"type":"string","title":"The identifier of the pool","description":"The identifier of the pool."}},"required":["amountIn","amountOut","price","priceImpact","fees","poolId"]}}}},"400":{"description":"Pool error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PoolNotFoundErrorByPoolId"},{"$ref":"#/components/schemas/PoolNotFoundErrorByToken"},{"$ref":"#/components/schemas/PoolAlreadyExistsError"},{"$ref":"#/components/schemas/InvalidFeeRateError"},{"$ref":"#/components/schemas/InvalidUtxoError"},{"$ref":"#/components/schemas/InvalidTokenError"},{"$ref":"#/components/schemas/NotEnoughFundsError"},{"$ref":"#/components/schemas/NotEnoughFundsForSplittingRuneError"},{"$ref":"#/components/schemas/ShardPubkeysRequiredError"},{"$ref":"#/components/schemas/RequestExpiredError"},{"$ref":"#/components/schemas/FailedToSendArchTransactionError"},{"$ref":"#/components/schemas/InvalidAddress"},{"$ref":"#/components/schemas/InvalidNumericValue"},{"$ref":"#/components/schemas/InvalidTxSizeError"},{"$ref":"#/components/schemas/InvalidRunestoneError"},{"$ref":"#/components/schemas/InvalidSignatureError"},{"$ref":"#/components/schemas/InvalidPsbtError"},{"$ref":"#/components/schemas/InvalidAmountBelowMinError"},{"$ref":"#/components/schemas/InvalidAmountError"},{"$ref":"#/components/schemas/InsufficientLiquidityError"},{"$ref":"#/components/schemas/ShardsUnavailableError"},{"$ref":"#/components/schemas/InvalidAssetPairError"},{"$ref":"#/components/schemas/InvalidFeeTierError"},{"$ref":"#/components/schemas/InvalidPubkeyError"}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"PoolNotFoundErrorByPoolId":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"PoolNotFoundErrorByToken":{"type":"object","properties":{"type":{"const":"PoolNotFound"},"token0":{"type":"string"},"token1":{"type":"string"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","token0","token1","message"]},"PoolAlreadyExistsError":{"type":"object","properties":{"type":{"const":"PoolAlreadyExists"},"poolId":{"type":"string"},"message":{"type":"string"}},"required":["type","poolId","message"]},"InvalidFeeRateError":{"type":"object","properties":{"type":{"const":"InvalidFeeRate"},"minFeeRate":{"type":"number"},"message":{"type":"string"}},"required":["type","minFeeRate","message"]},"InvalidUtxoError":{"type":"object","properties":{"type":{"const":"InvalidUtxo"},"utxos":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["type","utxos","message"]},"InvalidTokenError":{"type":"object","properties":{"type":{"const":"InvalidToken"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","token","message"]},"NotEnoughFundsError":{"type":"object","properties":{"type":{"const":"NotEnoughFunds"},"maxAmount":{"type":"string"},"minAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","maxAmount","minAmount","token","message"]},"NotEnoughFundsForSplittingRuneError":{"type":"object","properties":{"type":{"const":"NotEnoughFundsForSplittingRune"},"recommendedRuneAmount":{"type":"string"},"currentSatsAmount":{"type":"string"},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","recommendedRuneAmount","currentSatsAmount","token","message"]},"ShardPubkeysRequiredError":{"type":"object","properties":{"type":{"const":"ShardPubkeysRequired"},"message":{"type":"string"}},"required":["type","message"]},"RequestExpiredError":{"type":"object","properties":{"type":{"const":"RequestExpired"},"message":{"type":"string"}},"required":["type","message"]},"FailedToSendArchTransactionError":{"type":"object","properties":{"type":{"const":"FailedToSendArchTransaction"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAddress":{"type":"object","properties":{"type":{"const":"InvalidAddress"},"message":{"type":"string"}},"required":["type","message"]},"InvalidNumericValue":{"type":"object","properties":{"type":{"const":"InvalidNumericValue"},"message":{"type":"string"}},"required":["type","message"]},"InvalidTxSizeError":{"type":"object","properties":{"type":{"const":"InvalidTxSize"},"message":{"type":"string"}},"required":["type","message"]},"InvalidRunestoneError":{"type":"object","properties":{"type":{"const":"InvalidRunestone"},"message":{"type":"string"}},"required":["type","message"]},"InvalidSignatureError":{"type":"object","properties":{"type":{"const":"InvalidSignature"},"message":{"type":"string"}},"required":["type","message"]},"InvalidPsbtError":{"type":"object","properties":{"type":{"const":"InvalidPsbt"},"message":{"type":"string"}},"required":["type","message"]},"InvalidAmountBelowMinError":{"type":"object","properties":{"type":{"const":"InvalidAmountBelowMin"},"token":{"type":"string"},"minAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","minAmount","message"]},"InvalidAmountError":{"type":"object","properties":{"type":{"const":"InvalidAmount"},"token":{"type":"string"},"expectedAmount":{"type":"string"},"actualAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","expectedAmount","actualAmount","message"]},"InsufficientLiquidityError":{"type":"object","properties":{"type":{"const":"InsufficientLiquidity"},"token":{"type":"string"},"maxAmount":{"type":"string"},"message":{"type":"string"}},"required":["type","token","maxAmount","message"]},"ShardsUnavailableError":{"type":"object","properties":{"type":{"const":"ShardsUnavailable"},"reason":{"oneOf":[{"const":"MempoolConstraints"},{"const":"NoBalance"}]},"token":{"type":"string"},"message":{"type":"string"}},"required":["type","reason","token","message"]},"InvalidAssetPairError":{"type":"object","properties":{"type":{"const":"InvalidAssetPair"},"message":{"type":"string"}},"required":["type","message"]},"InvalidFeeTierError":{"type":"object","properties":{"type":{"const":"InvalidFeeTier"},"feeTier":{"type":"number"},"message":{"type":"string"}},"required":["type","feeTier","message"]},"InvalidPubkeyError":{"type":"object","properties":{"type":{"const":"InvalidPubkey"},"pubkey":{"type":"string"},"message":{"type":"string"}},"required":["type","pubkey","message"]}}}} ``` # Boost Transaction #### Overview * **Functionality**: Boost and broadcast transactions * **API Key authentication**: Access to all endpoints requires the `x-api-key` header provided by Saturn * **Address parameter**: All requests must have the `Content-Type` header of `application/json` and provide the `address` in the body of the wallet that is requesting the broadcast. **Endpoints** ## Boost an array of transaction ids. User must own some of the outputs of those transactions > Boost an array of transaction ids. User must own some of the outputs of those transactions.\ > The response will contain a PSBT that can be signed by the user.\ > You can then broadcast the PSBT using the \`/broadcast\` endpoint. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Transaction"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"IApiSpeedUpTransactionRequest":{"type":"object","properties":{"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."},"runePublicKey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The rune public key of the user","description":"The rune public key of the user."},"paymentPublicKey":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":66,"title":"The payment public key of the user","description":"The payment public key of the user."},"transactionIds":{"type":"array","items":{"type":"string"},"title":"The transaction ids to boost","description":"The transaction ids to boost."}},"required":["runeAddress","runePublicKey","transactionIds"]},"BoostTransactionResponse":{"type":"object","properties":{"psbt":{"type":"string","title":"The PSBT of the boosted transaction","description":"The PSBT of the boosted transaction."},"fee":{"type":"string","title":"The fee of the boosted transaction","description":"The fee of the boosted transaction."},"newFeeRate":{"type":"number","title":"The new fee rate of the boosted transaction","description":"The new fee rate of the boosted transaction."},"feeRate":{"type":"number","title":"The fee rate of the boosted transaction","description":"The fee rate of the boosted transaction."},"utxosToSign":{"type":"array","items":{"$ref":"#/components/schemas/InputToSign"},"title":"The inputs to sign for the boosted transaction","description":"The inputs to sign for the boosted transaction."}},"required":["psbt","fee","newFeeRate","feeRate","utxosToSign"]},"InputToSign":{"type":"object","properties":{"address":{"type":"string"},"signingIndexes":{"type":"array","items":{"type":"number"}},"sigHash":{"type":"number"},"utxo":{"type":"string"}},"required":["address","signingIndexes","utxo"]},"TransactionSpeedUpError":{"type":"object","properties":{"type":{"oneOf":[{"const":"HighFee"},{"const":"TxnAlreadyConfirmed"},{"const":"NotEnoughFunds"},{"const":"NoOutputsForUser"},{"const":"FailedToFinalizeInputs"},{"const":"TxnNotFound"}]},"message":{"type":"string"},"args":{}},"required":["type","message"]}}},"paths":{"/v0/transaction/boost":{"post":{"summary":"Boost an array of transaction ids. User must own some of the outputs of those transactions","description":"Boost an array of transaction ids. User must own some of the outputs of those transactions.\nThe response will contain a PSBT that can be signed by the user.\nYou can then broadcast the PSBT using the `/broadcast` endpoint.","tags":["Transaction"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IApiSpeedUpTransactionRequest"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoostTransactionResponse"}}}},"400":{"description":"Transaction speedup error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionSpeedUpError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` ## Broadcast a signed transaction > Broadcast a signed transaction. ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Transaction"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"IApiBroadcastPsbtRequest":{"type":"object","properties":{"runeAddress":{"type":"string","title":"The rune address of the user. It must be a taproot address. (P2TR)","description":"The rune address of the user. It must be a taproot address. (P2TR).\nIf no bitcoin address is provided, the rune address will be used for bitcoin too."},"paymentAddress":{"type":"string","title":"The bitcoin address of the user","description":"The bitcoin address of the user."},"signedPsbt":{"type":"string","title":"The signed PSBT of the transaction","description":"The signed PSBT of the transaction."},"txType":{"oneOf":[{"const":"trade"},{"const":"prepare_wallet"},{"const":"extract"},{"const":"purchase"},{"const":"vsrCreation"},{"const":"deposit"},{"const":"withdraw"},{"const":"mint"},{"const":"etch"},{"const":"initialize_pool"},{"const":"increase_liquidity"},{"const":"decrease_liquidity"},{"const":"open_position"},{"const":"add_pool_shards"},{"const":"swap"}],"title":"The type of the transaction","description":"The type of the transaction."}},"required":["runeAddress","signedPsbt","txType"]},"TransactionSpeedUpError":{"type":"object","properties":{"type":{"oneOf":[{"const":"HighFee"},{"const":"TxnAlreadyConfirmed"},{"const":"NotEnoughFunds"},{"const":"NoOutputsForUser"},{"const":"FailedToFinalizeInputs"},{"const":"TxnNotFound"}]},"message":{"type":"string"},"args":{}},"required":["type","message"]}}},"paths":{"/v0/transaction/broadcast":{"post":{"summary":"Broadcast a signed transaction","description":"Broadcast a signed transaction.","tags":["Transaction"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IApiBroadcastPsbtRequest"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Transaction speedup error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionSpeedUpError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"User not found","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` # Wallet #### Balance Endpoint **Overview** The Balance Endpoint offers comprehensive balance and transaction data for specified wallet addresses. This endpoint is specifically tailored to provide detailed insights into the runes and bitcoin associated with a given address. **Functionality** * **Address Parameter**: Users must specify a wallet address to query its balance and transaction data. * **Real-Time Data on Runes**: The endpoint focuses on providing detailed information about runes and bitcoin held in the queried wallet. * **UTXOs and UTXOsIds**: Understanding the difference between `utxos` and `utxosIds` is crucial: * **utxos**: This array contains detailed information about each unspent transaction output (UTXO) that has been parsed and is available for the specified wallet address. * **utxosIds**: Represents all UTXOs associated with the wallet, including those not yet parsed. Initially, new wallet queries may show only `utxosIds` without corresponding `utxos` data, indicating that parsing is pending. Subsequent queries will reveal detailed UTXO data as parsing is completed. **Endpoint Details** ## GET /v0/wallet/balance > Get wallet balance and UTXO data ```json {"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Wallet"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v0/wallet/balance":{"get":{"summary":"Get wallet balance and UTXO data","tags":["Wallet"],"parameters":[{"name":"address","in":"query","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Wallet - The wallet's balance runes, btc and UTXO data.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"balance":{"type":"string"},"utxosIds":{"type":"array","items":{"type":"string"}},"utxos":{"type":"array","items":{"type":"object","properties":{"collectionStatuses":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"const":"btc"},"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"oneOf":[{"type":"null"},{"type":"string"}]},"divisibility":{"type":"number"},"supply":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isWatchedByUser":{"type":"boolean"},"amount":{"type":"string"},"riskyAmount":{"type":"string"}},"required":["type","id","name","displayName","divisibility","supply","createdAt","updatedAt","isWatchedByUser","amount","riskyAmount"]},{"type":"object","properties":{"type":{"const":"rune"},"verified":{"type":"boolean"},"icon":{"oneOf":[{"type":"null"},{"type":"string"}]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"oneOf":[{"type":"null"},{"type":"string"}]},"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"oneOf":[{"type":"null"},{"type":"string"}]},"divisibility":{"type":"number"},"supply":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isWatchedByUser":{"type":"boolean"},"amount":{"type":"string"},"riskyAmount":{"type":"string"}},"required":["type","verified","premined","burned","id","name","displayName","divisibility","supply","createdAt","updatedAt","isWatchedByUser","amount","riskyAmount"]}]}},"isUsed":{"type":"boolean"},"hasInscription":{"type":"boolean"},"inscriptionIds":{"type":"array","items":{"type":"string"}},"txid":{"type":"string"},"vout":{"type":"number"},"status":{"type":"object","properties":{"confirmed":{"type":"boolean"},"block_height":{"type":"number"},"block_hash":{"type":"string"},"block_time":{"type":"number"}},"required":["confirmed"]},"value":{"type":"string"}},"required":["collectionStatuses","isUsed","hasInscription","inscriptionIds","txid","vout","status","value"]}}},"required":["address","balance","utxosIds","utxos"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}} ``` * **Parameters**: * `address` (string, required): The wallet address for which balance and UTXO data is requested. **Response Structure** The response from this endpoint provides a JSON object with the following key details: * `address`: The queried wallet address. * `balance`: The overall balance of the wallet. * `utxos`: An array of UTXO objects, each containing: * Details about its balance and associated collections. * Information on any inscriptions, including their content and metadata. * `utxosIds`: An array of UTXO IDs representing all UTXOs associated with the wallet. * Each UTXO and collection item contains additional fields such as market price, batch size, verification status, and timestamps. # Indexer API The **Indexer API** is a powerful tool designed to provide seamless access to blockchain data, enabling developers to interact with collections, pools, positions, transactions, and more. This API allows you to: * **Manage Collections**: Retrieve and search for collections (runes) with advanced filtering and sorting options. * **Access Pool Data**: Obtain detailed information about liquidity pools, including statistics and historical data. * **Monitor Positions**: Fetch user positions, estimated yields, and pool statistics. * **Query Transactions**: Access transaction histories for specific pools or users, with support for filtering by date, type, and tokens. * **Obtain Market Data**: Retrieve OHLC (Open, High, Low, Close) data for asset pairs to support trading and analysis applications. The Indexer API stands out for its robustness and flexibility, providing comprehensive endpoints that cater to a wide range of blockchain data needs. Its powerful querying capabilities make it an indispensable tool for developers building applications in the decentralized finance (DeFi) space. To make integration even more straightforward, we offer: * [**Typescript SDK**](https://www.npmjs.com/package/@saturnbtcio/indexer-api-sdk): A fully-featured SDK, allowing for easy and type-safe interactions with the API. * [**Swagger Documentation**](https://indexer.staging.saturnbtc.io/swagger): An OpenAPI specification is available, providing detailed information about each endpoint, request, and response format. # Collections ## POST /collection/mintable/multi-search > Search mintable collections using filter criteria ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"collection","description":"Fetch detailed information for runes indexed on Saturn"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/collection/mintable/multi-search":{"post":{"tags":["collection"],"description":"Search mintable collections using filter criteria","operationId":"mintable_multi_search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintableCollectionSearchFilter"}}},"required":true},"responses":{"200":{"description":"Paginated collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_MintableCollection"}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"MintableCollectionSearchFilter":{"type":"object","description":"Struct used to filter mintable collections.","properties":{"name":{"type":["string","null"]},"sort":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SortField_SortMintableFieldCollection"}},"limit":{"type":["integer","null"],"format":"int32"},"offset":{"type":["integer","null"],"format":"int32"}}},"SortField_SortMintableFieldCollection":{"type":"object","required":["field","order"],"properties":{"field":{"type":"string","enum":["id","name","supply","created_at","start","end","progress"]},"order":{"$ref":"#/components/schemas/SortOrder"}}},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"PaginationResponse_Vec_MintableCollection":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Collection"},{"type":"object","required":["mint"],"properties":{"mint":{"$ref":"#/components/schemas/MintEntity"}}}]}},"offset":{"type":"integer","format":"int32"}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"MintEntity":{"type":"object","required":["collection_id","mintable","mints","cap","amount"],"properties":{"collection_id":{"type":"string"},"start":{"type":["integer","null"],"format":"int64","minimum":0},"end":{"type":["integer","null"],"format":"int64","minimum":0},"mintable":{"type":"boolean"},"mints":{"type":"string"},"cap":{"type":"string"},"amount":{"type":"string"}}}}}} ``` ## POST /collection/multi-search > Get multiple collections using filter criteria ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"collection","description":"Fetch detailed information for runes indexed on Saturn"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/collection/multi-search":{"post":{"tags":["collection"],"description":"Get multiple collections using filter criteria","operationId":"multi_search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionSearchFilter"}}},"required":true},"responses":{"200":{"description":"Paginated collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_Collection"}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"CollectionSearchFilter":{"type":"object","description":"Struct used to filter collections.","properties":{"name":{"type":["string","null"]},"sort":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SortField_SortFieldCollection"}},"limit":{"type":["integer","null"],"format":"int32"},"offset":{"type":["integer","null"],"format":"int32"},"address":{"type":["string","null"]}}},"SortField_SortFieldCollection":{"type":"object","required":["field","order"],"properties":{"field":{"type":"string","enum":["id","name","supply","created_at"]},"order":{"$ref":"#/components/schemas/SortOrder"}}},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"PaginationResponse_Vec_Collection":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]}},"offset":{"type":"integer","format":"int32"}}},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` ## POST /collection/mintable/id > Get mintable collections by ids ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"collection","description":"Fetch detailed information for runes indexed on Saturn"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/collection/mintable/id":{"post":{"tags":["collection"],"description":"Get mintable collections by ids","operationId":"mintable_multi_search_by_id","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindManyByIdsRequest"}}},"required":true},"responses":{"200":{"description":"List of mintable collections","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MintableCollection"}}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"FindManyByIdsRequest":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}},"MintableCollection":{"allOf":[{"$ref":"#/components/schemas/Collection"},{"type":"object","required":["mint"],"properties":{"mint":{"$ref":"#/components/schemas/MintEntity"}}}]},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"MintEntity":{"type":"object","required":["collection_id","mintable","mints","cap","amount"],"properties":{"collection_id":{"type":"string"},"start":{"type":["integer","null"],"format":"int64","minimum":0},"end":{"type":["integer","null"],"format":"int64","minimum":0},"mintable":{"type":"boolean"},"mints":{"type":"string"},"cap":{"type":"string"},"amount":{"type":"string"}}}}}} ``` ## GET /collection/id/{id} > Get details for a single collection by ID ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"collection","description":"Fetch detailed information for runes indexed on Saturn"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/collection/id/{id}":{"get":{"tags":["collection"],"description":"Get details for a single collection by ID","operationId":"get_collection_by_id","parameters":[{"name":"id","in":"path","description":"ID of the collection","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` ## GET /collection/ids > Get multiple collection details by IDs ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"collection","description":"Fetch detailed information for runes indexed on Saturn"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/collection/ids":{"get":{"tags":["collection"],"description":"Get multiple collection details by IDs","operationId":"get_collections_by_ids","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"explode":false}],"responses":{"200":{"description":"List of collections","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` ## GET /collection/names > Get multiple collection that match the name query ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"collection","description":"Fetch detailed information for runes indexed on Saturn"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/collection/names":{"get":{"tags":["collection"],"description":"Get multiple collection that match the name query","operationId":"get_collections_by_names","parameters":[{"name":"names","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"explode":false}],"responses":{"200":{"description":"List of collections","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` # Pools ## GET /pool/by-id/{id} > Returns the pool and its latest state ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool/by-id/{id}":{"get":{"tags":["pool"],"description":"Returns the pool and its latest state","operationId":"find_one","parameters":[{"name":"id","in":"path","description":"Pool ID as hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Swap pool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifiableLiquidityPool"}}}},"400":{"description":"Invalid pubkey format"},"404":{"description":"Pool not found"}}}}},"components":{"schemas":{"IdentifiableLiquidityPool":{"allOf":[{"$ref":"#/components/schemas/LiquidityPool"},{"type":"object","required":["shards","token0Amount","token1Amount","liquidity","price"],"properties":{"shards":{"type":"array","items":{"$ref":"#/components/schemas/IdentifiableLiquidityPoolShard"}},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"price":{"type":"string"}}}]},"LiquidityPool":{"type":"object","required":["id","feeRate","config","assetPair","createdBlockHeight"],"properties":{"id":{"type":"string"},"feeRate":{"type":"integer","format":"int32"},"config":{"$ref":"#/components/schemas/LiquidityPoolConfig"},"assetPair":{"$ref":"#/components/schemas/AssetPair"},"createdBlockHeight":{"type":"string"}}},"LiquidityPoolConfig":{"type":"object","required":["feeTier","shards","token0","token1"],"properties":{"feeTier":{"type":"integer","format":"int32","minimum":0},"shards":{"type":"integer","format":"int32","minimum":0},"token0":{"type":"string"},"token1":{"type":"string"}}},"AssetPair":{"type":"object","required":["token0Id","token1Id"],"properties":{"token0Id":{"type":"string"},"token1Id":{"type":"string"}}},"IdentifiableLiquidityPoolShard":{"allOf":[{"$ref":"#/components/schemas/LiquidityPoolShardJson"},{"type":"object","required":["pubkey","utxo"],"properties":{"pubkey":{"type":"string"},"utxo":{"type":"string"}}}]},"LiquidityPoolShardJson":{"type":"object","required":["poolPubkey","btcUtxos","liquidity","protocolFeeOwed","kLast","kLastCounter","swapBalance"],"properties":{"poolPubkey":{"type":"string"},"runeUtxo":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/UtxoInfoJson","description":"UTXO holding runes for this shard"}]},"btcUtxos":{"type":"array","items":{"$ref":"#/components/schemas/UtxoInfoJson"},"description":"UTXOs holding BTC for this shard"},"liquidity":{"type":"string","description":"Liquidity held in this shard"},"protocolFeeOwed":{"type":"string","description":"How much BTC has accumulated as fees in this shard"},"kLast":{"type":"string"},"kLastCounter":{"type":"string"},"swapBalance":{"$ref":"#/components/schemas/SwapBalance"}}},"UtxoInfoJson":{"type":"object","required":["txid","vout","value","runes","needsConsolidation"],"properties":{"txid":{"type":"string"},"vout":{"type":"integer","format":"int32","minimum":0},"value":{"type":"string"},"runes":{"type":"array","items":{"$ref":"#/components/schemas/RuneAmountJson"}},"needsConsolidation":{"$ref":"#/components/schemas/NeedsConsolidation"}}},"RuneAmountJson":{"type":"object","required":["id","amount"],"properties":{"id":{"type":"string","format":"token"},"amount":{"type":"string"}}},"NeedsConsolidation":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["no"]}}},{"type":"object","description":"Internal f64 represents mempool fee rate at moment of creation.","required":["value","type"],"properties":{"value":{"type":"number","format":"double","description":"Internal f64 represents mempool fee rate at moment of creation."},"type":{"type":"string","enum":["yes"]}}}]},"SwapBalance":{"type":"object","required":["blockHeight","zeroToOneSwaps","oneToZeroSwaps"],"properties":{"blockHeight":{"type":"integer","format":"int64","minimum":0},"zeroToOneSwaps":{"type":"integer","format":"int32","minimum":0},"oneToZeroSwaps":{"type":"integer","format":"int32","minimum":0}}}}}} ``` ## GET /pool/by-token-names > Returns a list of pool details with its current state where the token names match. Search is case-insensitive and will find pools where either token matches any of the given ones ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool/by-token-names":{"get":{"tags":["pool"],"description":"Returns a list of pool details with its current state where the token names match. Search is case-insensitive and will find pools where either token matches any of the given ones","operationId":"find_many_by_token_names","parameters":[{"name":"token0","in":"query","required":true,"schema":{"type":"string"}},{"name":"token1","in":"query","required":true,"schema":{"type":"string"}},{"name":"feeTier","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}}],"responses":{"200":{"description":"Swap pools","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IdentifiableLiquidityPool"}}}}},"404":{"description":"No matching pools found"}}}}},"components":{"schemas":{"IdentifiableLiquidityPool":{"allOf":[{"$ref":"#/components/schemas/LiquidityPool"},{"type":"object","required":["shards","token0Amount","token1Amount","liquidity","price"],"properties":{"shards":{"type":"array","items":{"$ref":"#/components/schemas/IdentifiableLiquidityPoolShard"}},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"price":{"type":"string"}}}]},"LiquidityPool":{"type":"object","required":["id","feeRate","config","assetPair","createdBlockHeight"],"properties":{"id":{"type":"string"},"feeRate":{"type":"integer","format":"int32"},"config":{"$ref":"#/components/schemas/LiquidityPoolConfig"},"assetPair":{"$ref":"#/components/schemas/AssetPair"},"createdBlockHeight":{"type":"string"}}},"LiquidityPoolConfig":{"type":"object","required":["feeTier","shards","token0","token1"],"properties":{"feeTier":{"type":"integer","format":"int32","minimum":0},"shards":{"type":"integer","format":"int32","minimum":0},"token0":{"type":"string"},"token1":{"type":"string"}}},"AssetPair":{"type":"object","required":["token0Id","token1Id"],"properties":{"token0Id":{"type":"string"},"token1Id":{"type":"string"}}},"IdentifiableLiquidityPoolShard":{"allOf":[{"$ref":"#/components/schemas/LiquidityPoolShardJson"},{"type":"object","required":["pubkey","utxo"],"properties":{"pubkey":{"type":"string"},"utxo":{"type":"string"}}}]},"LiquidityPoolShardJson":{"type":"object","required":["poolPubkey","btcUtxos","liquidity","protocolFeeOwed","kLast","kLastCounter","swapBalance"],"properties":{"poolPubkey":{"type":"string"},"runeUtxo":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/UtxoInfoJson","description":"UTXO holding runes for this shard"}]},"btcUtxos":{"type":"array","items":{"$ref":"#/components/schemas/UtxoInfoJson"},"description":"UTXOs holding BTC for this shard"},"liquidity":{"type":"string","description":"Liquidity held in this shard"},"protocolFeeOwed":{"type":"string","description":"How much BTC has accumulated as fees in this shard"},"kLast":{"type":"string"},"kLastCounter":{"type":"string"},"swapBalance":{"$ref":"#/components/schemas/SwapBalance"}}},"UtxoInfoJson":{"type":"object","required":["txid","vout","value","runes","needsConsolidation"],"properties":{"txid":{"type":"string"},"vout":{"type":"integer","format":"int32","minimum":0},"value":{"type":"string"},"runes":{"type":"array","items":{"$ref":"#/components/schemas/RuneAmountJson"}},"needsConsolidation":{"$ref":"#/components/schemas/NeedsConsolidation"}}},"RuneAmountJson":{"type":"object","required":["id","amount"],"properties":{"id":{"type":"string","format":"token"},"amount":{"type":"string"}}},"NeedsConsolidation":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["no"]}}},{"type":"object","description":"Internal f64 represents mempool fee rate at moment of creation.","required":["value","type"],"properties":{"value":{"type":"number","format":"double","description":"Internal f64 represents mempool fee rate at moment of creation."},"type":{"type":"string","enum":["yes"]}}}]},"SwapBalance":{"type":"object","required":["blockHeight","zeroToOneSwaps","oneToZeroSwaps"],"properties":{"blockHeight":{"type":"integer","format":"int64","minimum":0},"zeroToOneSwaps":{"type":"integer","format":"int32","minimum":0},"oneToZeroSwaps":{"type":"integer","format":"int32","minimum":0}}}}}} ``` ## GET /pool/by-token-ids > Returns a list of pool details with its current state, where the provided ids match exactly and are optionally filtered by the fee tier ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool/by-token-ids":{"get":{"tags":["pool"],"description":"Returns a list of pool details with its current state, where the provided ids match exactly and are optionally filtered by the fee tier","operationId":"find_many_by_token_ids","parameters":[{"name":"token0","in":"query","required":true,"schema":{"type":"string"}},{"name":"token1","in":"query","required":true,"schema":{"type":"string"}},{"name":"feeTier","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}}],"responses":{"200":{"description":"Swap pools","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IdentifiableLiquidityPool"}}}}},"404":{"description":"No matching pools found"}}}}},"components":{"schemas":{"IdentifiableLiquidityPool":{"allOf":[{"$ref":"#/components/schemas/LiquidityPool"},{"type":"object","required":["shards","token0Amount","token1Amount","liquidity","price"],"properties":{"shards":{"type":"array","items":{"$ref":"#/components/schemas/IdentifiableLiquidityPoolShard"}},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"price":{"type":"string"}}}]},"LiquidityPool":{"type":"object","required":["id","feeRate","config","assetPair","createdBlockHeight"],"properties":{"id":{"type":"string"},"feeRate":{"type":"integer","format":"int32"},"config":{"$ref":"#/components/schemas/LiquidityPoolConfig"},"assetPair":{"$ref":"#/components/schemas/AssetPair"},"createdBlockHeight":{"type":"string"}}},"LiquidityPoolConfig":{"type":"object","required":["feeTier","shards","token0","token1"],"properties":{"feeTier":{"type":"integer","format":"int32","minimum":0},"shards":{"type":"integer","format":"int32","minimum":0},"token0":{"type":"string"},"token1":{"type":"string"}}},"AssetPair":{"type":"object","required":["token0Id","token1Id"],"properties":{"token0Id":{"type":"string"},"token1Id":{"type":"string"}}},"IdentifiableLiquidityPoolShard":{"allOf":[{"$ref":"#/components/schemas/LiquidityPoolShardJson"},{"type":"object","required":["pubkey","utxo"],"properties":{"pubkey":{"type":"string"},"utxo":{"type":"string"}}}]},"LiquidityPoolShardJson":{"type":"object","required":["poolPubkey","btcUtxos","liquidity","protocolFeeOwed","kLast","kLastCounter","swapBalance"],"properties":{"poolPubkey":{"type":"string"},"runeUtxo":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/UtxoInfoJson","description":"UTXO holding runes for this shard"}]},"btcUtxos":{"type":"array","items":{"$ref":"#/components/schemas/UtxoInfoJson"},"description":"UTXOs holding BTC for this shard"},"liquidity":{"type":"string","description":"Liquidity held in this shard"},"protocolFeeOwed":{"type":"string","description":"How much BTC has accumulated as fees in this shard"},"kLast":{"type":"string"},"kLastCounter":{"type":"string"},"swapBalance":{"$ref":"#/components/schemas/SwapBalance"}}},"UtxoInfoJson":{"type":"object","required":["txid","vout","value","runes","needsConsolidation"],"properties":{"txid":{"type":"string"},"vout":{"type":"integer","format":"int32","minimum":0},"value":{"type":"string"},"runes":{"type":"array","items":{"$ref":"#/components/schemas/RuneAmountJson"}},"needsConsolidation":{"$ref":"#/components/schemas/NeedsConsolidation"}}},"RuneAmountJson":{"type":"object","required":["id","amount"],"properties":{"id":{"type":"string","format":"token"},"amount":{"type":"string"}}},"NeedsConsolidation":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["no"]}}},{"type":"object","description":"Internal f64 represents mempool fee rate at moment of creation.","required":["value","type"],"properties":{"value":{"type":"number","format":"double","description":"Internal f64 represents mempool fee rate at moment of creation."},"type":{"type":"string","enum":["yes"]}}}]},"SwapBalance":{"type":"object","required":["blockHeight","zeroToOneSwaps","oneToZeroSwaps"],"properties":{"blockHeight":{"type":"integer","format":"int64","minimum":0},"zeroToOneSwaps":{"type":"integer","format":"int32","minimum":0},"oneToZeroSwaps":{"type":"integer","format":"int32","minimum":0}}}}}} ``` ## POST /pool/stats/by-filter > Returns a paginated list of pool statistics matching the provided filter criteria ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool/stats/by-filter":{"post":{"tags":["pool"],"description":"Returns a paginated list of pool statistics matching the provided filter criteria","operationId":"find_by_filter","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolSearchFilter"}}},"required":true},"responses":{"200":{"description":"swap pool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_PoolStats"}}}},"404":{"description":"no matching pools found"}}}}},"components":{"schemas":{"PoolSearchFilter":{"type":"object","properties":{"name":{"type":["array","null"],"items":{"type":"string"}},"minTvl":{"type":["integer","null"],"format":"int64"},"minVolume":{"type":["integer","null"],"format":"int64"},"sort":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SortField_SortFieldPool"}},"limit":{"type":["integer","null"],"format":"int32"},"offset":{"type":["integer","null"],"format":"int32"},"userAddress":{"type":["string","null"]}}},"SortField_SortFieldPool":{"type":"object","required":["field","order"],"properties":{"field":{"type":"string","enum":["token0_name","token1_name","tvl_now","tvl_24h_ago","tvl_diff","volume_24h","volume_7d","volume_diff_24h","fees_24h","fees_7d","smaller_24h_apy","larger_24h_apy","smaller_7d_apy","larger_7d_apy"]},"order":{"$ref":"#/components/schemas/SortOrder"}}},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"PaginationResponse_Vec_PoolStats":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"type":"object","required":["poolId","token0","token1","token0Amount","token1Amount","liquidity","price","feeRate"],"properties":{"poolId":{"type":"string"},"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"price":{"type":"string"},"tvlNow":{"type":["string","null"]},"tvl24hAgo":{"type":["string","null"]},"tvlDiff":{"type":["string","null"]},"volume24h":{"type":["string","null"]},"volumePrev24h":{"type":["string","null"]},"volumeDiff24h":{"type":["string","null"]},"fees24h":{"type":["string","null"]},"apy24h":{"type":["string","null"]},"volume7d":{"type":["string","null"]},"fees7d":{"type":["string","null"]},"apy7d":{"type":["string","null"]},"feeRate":{"type":"integer","format":"int32","minimum":0}}}},"offset":{"type":"integer","format":"int32"}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` ## GET /pool/stats/by-ids > Returns a list of detailed statistics for pools matching the provided IDs, including token information, TVL, volume, fees, and APY data. ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool/stats/by-ids":{"get":{"tags":["pool"],"description":"Returns a list of detailed statistics for pools matching the provided IDs, including token information, TVL, volume, fees, and APY data.","operationId":"find_by_ids","parameters":[{"name":"poolIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"explode":false}],"responses":{"200":{"description":"swap pools","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PoolStats"}}}}},"404":{"description":"No matching pools found"}}}}},"components":{"schemas":{"PoolStats":{"type":"object","required":["poolId","token0","token1","token0Amount","token1Amount","liquidity","price","feeRate"],"properties":{"poolId":{"type":"string"},"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"price":{"type":"string"},"tvlNow":{"type":["string","null"]},"tvl24hAgo":{"type":["string","null"]},"tvlDiff":{"type":["string","null"]},"volume24h":{"type":["string","null"]},"volumePrev24h":{"type":["string","null"]},"volumeDiff24h":{"type":["string","null"]},"fees24h":{"type":["string","null"]},"apy24h":{"type":["string","null"]},"volume7d":{"type":["string","null"]},"fees7d":{"type":["string","null"]},"apy7d":{"type":["string","null"]},"feeRate":{"type":"integer","format":"int32","minimum":0}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` ## POST /pool/stats/by-token-filter > Returns a paginated list of token pairs with aggregated pool statistics filtered by the provided criteria ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool/stats/by-token-filter":{"post":{"tags":["pool"],"description":"Returns a paginated list of token pairs with aggregated pool statistics filtered by the provided criteria","operationId":"find_by_token_filter","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolSearchFilter"}}},"required":true},"responses":{"200":{"description":"swap pools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_PoolsStatsByTokens"}}}},"404":{"description":"no matching pools found"}}}}},"components":{"schemas":{"PoolSearchFilter":{"type":"object","properties":{"name":{"type":["array","null"],"items":{"type":"string"}},"minTvl":{"type":["integer","null"],"format":"int64"},"minVolume":{"type":["integer","null"],"format":"int64"},"sort":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SortField_SortFieldPool"}},"limit":{"type":["integer","null"],"format":"int32"},"offset":{"type":["integer","null"],"format":"int32"},"userAddress":{"type":["string","null"]}}},"SortField_SortFieldPool":{"type":"object","required":["field","order"],"properties":{"field":{"type":"string","enum":["token0_name","token1_name","tvl_now","tvl_24h_ago","tvl_diff","volume_24h","volume_7d","volume_diff_24h","fees_24h","fees_7d","smaller_24h_apy","larger_24h_apy","smaller_7d_apy","larger_7d_apy"]},"order":{"$ref":"#/components/schemas/SortOrder"}}},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"PaginationResponse_Vec_PoolsStatsByTokens":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"type":"object","required":["token0","token1","tvlNow","tvl24hAgo","tvlDiff","pools"],"properties":{"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"},"volume24h":{"type":["string","null"]},"volumeDiff24h":{"type":["string","null"]},"volume7d":{"type":["string","null"]},"fees24h":{"type":["string","null"]},"tvlNow":{"type":"string"},"tvl24hAgo":{"type":"string"},"tvlDiff":{"type":"string"},"smaller24hApy":{"type":["string","null"]},"larger24hApy":{"type":["string","null"]},"smaller7dApy":{"type":["string","null"]},"larger7dApy":{"type":["string","null"]},"pools":{"type":"array","items":{"$ref":"#/components/schemas/GroupedPoolStat"}}}}},"offset":{"type":"integer","format":"int32"}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"GroupedPoolStat":{"type":"object","required":["id","tvlNow","tvl24hAgo","tvlDiff","price","token0Amount","token1Amount","liquidity","feeRate"],"properties":{"id":{"type":"string"},"tvlNow":{"type":"string"},"tvl24hAgo":{"type":"string"},"tvlDiff":{"type":"string"},"volume24h":{"type":["string","null"]},"volumeDiff24h":{"type":["string","null"]},"fees24h":{"type":["string","null"]},"apy24h":{"type":["number","null"],"format":"double"},"volume7d":{"type":["string","null"]},"fees7d":{"type":["string","null"]},"apy7d":{"type":["number","null"],"format":"double"},"price":{"type":"string"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"feeRate":{"type":"integer","format":"int32"}}}}}} ``` ## GET /pool > Paginated list of swap pools stats matched by the filter ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"pool","description":"Fetch details of Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/pool":{"get":{"tags":["pool"],"description":"Paginated list of swap pools stats matched by the filter","operationId":"find","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"sortVolume","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"sortFeeGenerated","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}},{"name":"offset","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}}],"responses":{"200":{"description":"swap pools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_PoolStats"}}}}}}}},"components":{"schemas":{"PaginationResponse_Vec_PoolStats":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"type":"object","required":["poolId","token0","token1","token0Amount","token1Amount","liquidity","price","feeRate"],"properties":{"poolId":{"type":"string"},"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"liquidity":{"type":"string"},"price":{"type":"string"},"tvlNow":{"type":["string","null"]},"tvl24hAgo":{"type":["string","null"]},"tvlDiff":{"type":["string","null"]},"volume24h":{"type":["string","null"]},"volumePrev24h":{"type":["string","null"]},"volumeDiff24h":{"type":["string","null"]},"fees24h":{"type":["string","null"]},"apy24h":{"type":["string","null"]},"volume7d":{"type":["string","null"]},"fees7d":{"type":["string","null"]},"apy7d":{"type":["string","null"]},"feeRate":{"type":"integer","format":"int32","minimum":0}}}},"offset":{"type":"integer","format":"int32"}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` # Prices ## GET /price > ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"price","description":"Price information for tokens"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/price":{"get":{"tags":["price"],"operationId":"get_prices_for_collections","parameters":[{"name":"collectionIds","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"explode":false}],"responses":{"200":{"description":"List of prices for matching collections","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Price"}}}}}}}}},"components":{"schemas":{"Price":{"type":"object","required":["blockHeight","token0Id","btcPrice"],"properties":{"blockHeight":{"type":"string"},"token0Id":{"type":"string"},"btcPrice":{"type":"string"}}}}}} ``` # Positions ## POST /positions/{pubkey}/by-filter > Get paginated positions for a user that match the specified filter ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/positions/{pubkey}/by-filter":{"post":{"tags":["position"],"description":"Get paginated positions for a user that match the specified filter","operationId":"get_positions_by_filter","parameters":[{"name":"pubkey","in":"path","description":"User's pubkey as hex string","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionSearchFilter"}}},"required":true},"responses":{"200":{"description":"Paginated positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_PositionResult"}}}},"400":{"description":"Invalid pubkey format"}}}}},"components":{"schemas":{"PositionSearchFilter":{"type":"object","properties":{"name":{"type":["array","null"],"items":{"type":"string"}},"min_liquidity":{"type":["integer","null"],"format":"int32"},"offset":{"type":["integer","null"],"format":"int32"},"limit":{"type":["integer","null"],"format":"int32"}}},"PaginationResponse_Vec_PositionResult":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"type":"object","required":["position","state","historicalGainPct","totalIncrementToken0Amount","totalIncrementToken1Amount"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"},"historicalGainPct":{"type":"string"},"totalIncrementToken0Amount":{"type":"integer"},"totalIncrementToken1Amount":{"type":"integer"},"estimatedApy24h":{"type":["string","null"]},"estimatedApy7d":{"type":["string","null"]}}}},"offset":{"type":"integer","format":"int32"}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}}}}} ``` ## GET /position/{id} > Get position details ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/position/{id}":{"get":{"tags":["position"],"description":"Get position details","operationId":"get_position_by_id","parameters":[{"name":"id","in":"path","description":"Position pubkey as hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Position details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionDetails"}}}},"400":{"description":"Invalid pubkey format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Position not found","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"PositionDetails":{"type":"object","required":["position","state"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}},"ApiError":{"oneOf":[{"type":"object","required":["DBError"],"properties":{"DBError":{"type":"string"}}},{"type":"object","required":["NotFound"],"properties":{"NotFound":{"type":"string"}}},{"type":"object","required":["InvalidPubkey"],"properties":{"InvalidPubkey":{"type":"string"}}}]}}}} ``` ## GET /position/{pubkey}/{pool\_id} > Get details for a user's position in the specified pool ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/position/{pubkey}/{pool_id}":{"get":{"tags":["position"],"description":"Get details for a user's position in the specified pool","operationId":"get_position_by_pubkey_and_pool","parameters":[{"name":"pubkey","in":"path","description":"User's pubkey as hex string","required":true,"schema":{"type":"string"}},{"name":"pool_id","in":"path","description":"Pool ID as a hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionResult"}}}},"400":{"description":"Invalid pubkey format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Position not found for specified pool","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"PositionResult":{"type":"object","required":["position","state","historicalGainPct","totalIncrementToken0Amount","totalIncrementToken1Amount"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"},"historicalGainPct":{"type":"string"},"totalIncrementToken0Amount":{"type":"integer"},"totalIncrementToken1Amount":{"type":"integer"},"estimatedApy24h":{"type":["string","null"]},"estimatedApy7d":{"type":["string","null"]}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}},"ApiError":{"oneOf":[{"type":"object","required":["DBError"],"properties":{"DBError":{"type":"string"}}},{"type":"object","required":["NotFound"],"properties":{"NotFound":{"type":"string"}}},{"type":"object","required":["InvalidPubkey"],"properties":{"InvalidPubkey":{"type":"string"}}}]}}}} ``` ## GET /positions/{pubkey} > Get a list of positions owned by the user ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/positions/{pubkey}":{"get":{"tags":["position"],"description":"Get a list of positions owned by the user","operationId":"get_positions_by_pubkey","parameters":[{"name":"pubkey","in":"path","description":"User's pubkey as hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of positions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PositionResult"}}}}},"400":{"description":"Invalid pubkey format"}}}}},"components":{"schemas":{"PositionResult":{"type":"object","required":["position","state","historicalGainPct","totalIncrementToken0Amount","totalIncrementToken1Amount"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"},"historicalGainPct":{"type":"string"},"totalIncrementToken0Amount":{"type":"integer"},"totalIncrementToken1Amount":{"type":"integer"},"estimatedApy24h":{"type":["string","null"]},"estimatedApy7d":{"type":["string","null"]}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}}}}} ``` # Transactions ## GET /transaction/pool/{pool\_id} > Get a paginated list of all transactions in the specified pool that match the provided filter ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"transaction","description":"Bitcoin transactions created on the Saturn platform"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/transaction/pool/{pool_id}":{"get":{"tags":["transaction"],"description":"Get a paginated list of all transactions in the specified pool that match the provided filter","operationId":"find_transactions_by_pool_id","parameters":[{"name":"pool_id","in":"path","description":"Pool ID in hex format","required":true,"schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"endDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"poolId","in":"query","description":"Optional pool filter; hex-encoded pool id","required":false,"schema":{"type":["string","null"]}},{"name":"token0","in":"query","description":"Optional asset pair filter; provide both tokens to filter by a specific pair","required":false,"schema":{"type":["string","null"]}},{"name":"token1","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"types","in":"query","required":false,"schema":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TransactionType"}},"explode":false},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}},{"name":"sortCreatedAt","in":"query","required":false,"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SortOrder"}]}},{"name":"bitcoinTxStatus","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"List of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorResponse_Vec_Transaction"}}}},"400":{"description":"Invalid pubkey format"}}}}},"components":{"schemas":{"TransactionType":{"type":"string","enum":["open_position","close_position","increase_liquidity","decrease_liquidity","swap","initialize_pool","add_pool_shards","collect_protocol_fees","initialize_protocol","set_owner","toggle_paused","SetFeeTiers"]},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"CursorResponse_Vec_Transaction":{"type":"object","required":["response"],"properties":{"response":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SuccessfulTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]}},"nextCursor":{"type":["string","null"]}}},"SuccessfulTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"bitcoinTxId":{"type":["string","null"]},"bitcoinBlockHeight":{"type":["integer","null"],"format":"int64","minimum":0},"bitcoinTxStatus":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BitcoinTxStatus"}]},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}},"StatusSchema":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["queued"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["processed"]}}},{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["failed"]}}}]},"RollbackStatusSchema":{"oneOf":[{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["rolledback"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["notRolledback"]}}}]},"BitcoinTxStatus":{"type":"string","enum":["pending","confirmed","failed","rolled_back"]},"TransactionDetails":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/InitializeProtocolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_protocol"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetOwnerData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_owner"]}}}]},{"allOf":[{"$ref":"#/components/schemas/TogglePausedData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["toggle_paused"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetFeeTiersData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_fee_tiers"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["open_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["increase_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["decrease_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["close_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/AddPoolShardsData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["add_pool_shards"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SwapData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["swap"]}}}]},{"allOf":[{"$ref":"#/components/schemas/CollectProtocolFeesData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["collect_protocol_fees"]}}}]},{"allOf":[{"$ref":"#/components/schemas/InitializePoolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_pool"]}}}]}]},"InitializeProtocolData":{"type":"object"},"SetOwnerData":{"type":"object","required":["owner"],"properties":{"owner":{"type":"string"}}},"TogglePausedData":{"type":"object","required":["paused"],"properties":{"paused":{"type":"boolean"}}},"SetFeeTiersData":{"type":"object","required":["feeTiers"],"properties":{"feeTiers":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}},"PositionData":{"type":"object","required":["positionId","token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid","prevTransactions"],"properties":{"positionId":{"type":"string"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransactions":{"type":"array","items":{"type":"string"}}}},"AddPoolShardsData":{"type":"object","required":["shards","diffShards","btcFeePaid","totalBtcFeePaid"],"properties":{"shards":{"type":"integer","format":"int32","minimum":0},"diffShards":{"type":"integer","format":"int32","minimum":0},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"SwapData":{"type":"object","required":["amountIn","amountOut","zeroToOne","btcFeePaid","totalBtcFeePaid"],"properties":{"amountIn":{"type":"string"},"amountOut":{"type":"string"},"zeroToOne":{"type":"boolean"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"CollectProtocolFeesData":{"type":"object","required":["token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid"],"properties":{"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"InitializePoolData":{"type":"object","required":["btcFeePaid","totalBtcFeePaid"],"properties":{"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"FailedTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}}}}} ``` ## GET /transaction/user/{pubkey} > Fetches a paginated list of user's transactions that match the provided filter ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"transaction","description":"Bitcoin transactions created on the Saturn platform"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/transaction/user/{pubkey}":{"get":{"tags":["transaction"],"description":"Fetches a paginated list of user's transactions that match the provided filter","operationId":"find_transactions_by_user","parameters":[{"name":"pubkey","in":"path","description":"User public key in hex format","required":true,"schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"endDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"poolId","in":"query","description":"Optional pool filter; hex-encoded pool id","required":false,"schema":{"type":["string","null"]}},{"name":"token0","in":"query","description":"Optional asset pair filter; provide both tokens to filter by a specific pair","required":false,"schema":{"type":["string","null"]}},{"name":"token1","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"types","in":"query","required":false,"schema":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TransactionType"}},"explode":false},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}},{"name":"sortCreatedAt","in":"query","required":false,"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SortOrder"}]}},{"name":"bitcoinTxStatus","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"Paginated list of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorResponse_Vec_TransactionResponse"}}}},"400":{"description":"Invalid pubkey format"}}}}},"components":{"schemas":{"TransactionType":{"type":"string","enum":["open_position","close_position","increase_liquidity","decrease_liquidity","swap","initialize_pool","add_pool_shards","collect_protocol_fees","initialize_protocol","set_owner","toggle_paused","SetFeeTiers"]},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"CursorResponse_Vec_TransactionResponse":{"type":"object","required":["response"],"properties":{"response":{"type":"array","items":{"type":"object","required":["transaction","token0","token1"],"properties":{"transaction":{"$ref":"#/components/schemas/Transaction"},"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"}}}},"nextCursor":{"type":["string","null"]}}},"Transaction":{"oneOf":[{"$ref":"#/components/schemas/SuccessfulTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]},"SuccessfulTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"bitcoinTxId":{"type":["string","null"]},"bitcoinBlockHeight":{"type":["integer","null"],"format":"int64","minimum":0},"bitcoinTxStatus":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BitcoinTxStatus"}]},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}},"StatusSchema":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["queued"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["processed"]}}},{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["failed"]}}}]},"RollbackStatusSchema":{"oneOf":[{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["rolledback"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["notRolledback"]}}}]},"BitcoinTxStatus":{"type":"string","enum":["pending","confirmed","failed","rolled_back"]},"TransactionDetails":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/InitializeProtocolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_protocol"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetOwnerData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_owner"]}}}]},{"allOf":[{"$ref":"#/components/schemas/TogglePausedData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["toggle_paused"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetFeeTiersData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_fee_tiers"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["open_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["increase_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["decrease_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["close_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/AddPoolShardsData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["add_pool_shards"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SwapData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["swap"]}}}]},{"allOf":[{"$ref":"#/components/schemas/CollectProtocolFeesData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["collect_protocol_fees"]}}}]},{"allOf":[{"$ref":"#/components/schemas/InitializePoolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_pool"]}}}]}]},"InitializeProtocolData":{"type":"object"},"SetOwnerData":{"type":"object","required":["owner"],"properties":{"owner":{"type":"string"}}},"TogglePausedData":{"type":"object","required":["paused"],"properties":{"paused":{"type":"boolean"}}},"SetFeeTiersData":{"type":"object","required":["feeTiers"],"properties":{"feeTiers":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}},"PositionData":{"type":"object","required":["positionId","token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid","prevTransactions"],"properties":{"positionId":{"type":"string"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransactions":{"type":"array","items":{"type":"string"}}}},"AddPoolShardsData":{"type":"object","required":["shards","diffShards","btcFeePaid","totalBtcFeePaid"],"properties":{"shards":{"type":"integer","format":"int32","minimum":0},"diffShards":{"type":"integer","format":"int32","minimum":0},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"SwapData":{"type":"object","required":["amountIn","amountOut","zeroToOne","btcFeePaid","totalBtcFeePaid"],"properties":{"amountIn":{"type":"string"},"amountOut":{"type":"string"},"zeroToOne":{"type":"boolean"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"CollectProtocolFeesData":{"type":"object","required":["token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid"],"properties":{"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"InitializePoolData":{"type":"object","required":["btcFeePaid","totalBtcFeePaid"],"properties":{"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"FailedTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` ## GET /transaction/all > Paginated list of all transactions that match the provided filter ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"transaction","description":"Bitcoin transactions created on the Saturn platform"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/transaction/all":{"get":{"tags":["transaction"],"description":"Paginated list of all transactions that match the provided filter","operationId":"find_all_transactions","parameters":[{"name":"startDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"endDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"poolId","in":"query","description":"Optional pool filter; hex-encoded pool id","required":false,"schema":{"type":["string","null"]}},{"name":"token0","in":"query","description":"Optional asset pair filter; provide both tokens to filter by a specific pair","required":false,"schema":{"type":["string","null"]}},{"name":"token1","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"types","in":"query","required":false,"schema":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TransactionType"}},"explode":false},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}},{"name":"sortCreatedAt","in":"query","required":false,"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SortOrder"}]}},{"name":"bitcoinTxStatus","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"Paginated list of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorResponse_Vec_Transaction"}}}}}}}},"components":{"schemas":{"TransactionType":{"type":"string","enum":["open_position","close_position","increase_liquidity","decrease_liquidity","swap","initialize_pool","add_pool_shards","collect_protocol_fees","initialize_protocol","set_owner","toggle_paused","SetFeeTiers"]},"SortOrder":{"type":"string","enum":["ASC","DESC"]},"CursorResponse_Vec_Transaction":{"type":"object","required":["response"],"properties":{"response":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SuccessfulTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]}},"nextCursor":{"type":["string","null"]}}},"SuccessfulTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"bitcoinTxId":{"type":["string","null"]},"bitcoinBlockHeight":{"type":["integer","null"],"format":"int64","minimum":0},"bitcoinTxStatus":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BitcoinTxStatus"}]},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}},"StatusSchema":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["queued"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["processed"]}}},{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["failed"]}}}]},"RollbackStatusSchema":{"oneOf":[{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["rolledback"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["notRolledback"]}}}]},"BitcoinTxStatus":{"type":"string","enum":["pending","confirmed","failed","rolled_back"]},"TransactionDetails":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/InitializeProtocolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_protocol"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetOwnerData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_owner"]}}}]},{"allOf":[{"$ref":"#/components/schemas/TogglePausedData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["toggle_paused"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetFeeTiersData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_fee_tiers"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["open_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["increase_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["decrease_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["close_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/AddPoolShardsData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["add_pool_shards"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SwapData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["swap"]}}}]},{"allOf":[{"$ref":"#/components/schemas/CollectProtocolFeesData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["collect_protocol_fees"]}}}]},{"allOf":[{"$ref":"#/components/schemas/InitializePoolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_pool"]}}}]}]},"InitializeProtocolData":{"type":"object"},"SetOwnerData":{"type":"object","required":["owner"],"properties":{"owner":{"type":"string"}}},"TogglePausedData":{"type":"object","required":["paused"],"properties":{"paused":{"type":"boolean"}}},"SetFeeTiersData":{"type":"object","required":["feeTiers"],"properties":{"feeTiers":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}},"PositionData":{"type":"object","required":["positionId","token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid","prevTransactions"],"properties":{"positionId":{"type":"string"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransactions":{"type":"array","items":{"type":"string"}}}},"AddPoolShardsData":{"type":"object","required":["shards","diffShards","btcFeePaid","totalBtcFeePaid"],"properties":{"shards":{"type":"integer","format":"int32","minimum":0},"diffShards":{"type":"integer","format":"int32","minimum":0},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"SwapData":{"type":"object","required":["amountIn","amountOut","zeroToOne","btcFeePaid","totalBtcFeePaid"],"properties":{"amountIn":{"type":"string"},"amountOut":{"type":"string"},"zeroToOne":{"type":"boolean"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"CollectProtocolFeesData":{"type":"object","required":["token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid"],"properties":{"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"InitializePoolData":{"type":"object","required":["btcFeePaid","totalBtcFeePaid"],"properties":{"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"FailedTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}}}}} ``` ## GET /transaction/swaps > List of swap transactions for specific collections ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"transaction","description":"Bitcoin transactions created on the Saturn platform"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/transaction/swaps":{"get":{"tags":["transaction"],"description":"List of swap transactions for specific collections","operationId":"find_swaps_by_collections","parameters":[{"name":"token0","in":"query","required":true,"schema":{"type":"string"}},{"name":"token1","in":"query","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Optional status filter; defaults to processed when not provided","required":false,"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TransactionStatusFilter"}]}},{"name":"rollbackStatus","in":"query","description":"Optional rollback status filter","required":false,"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RollbackStatusFilter"}]}},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32"}}],"responses":{"200":{"description":"Paginated list of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorResponse_Vec_TransactionResponse"}}}}}}}},"components":{"schemas":{"TransactionStatusFilter":{"type":"string","description":"Filter for high-level transaction processing status","enum":["processed","failed"]},"RollbackStatusFilter":{"type":"string","description":"Filter for rollback state","enum":["not_rolledback","rolledback"]},"CursorResponse_Vec_TransactionResponse":{"type":"object","required":["response"],"properties":{"response":{"type":"array","items":{"type":"object","required":["transaction","token0","token1"],"properties":{"transaction":{"$ref":"#/components/schemas/Transaction"},"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"}}}},"nextCursor":{"type":["string","null"]}}},"Transaction":{"oneOf":[{"$ref":"#/components/schemas/SuccessfulTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]},"SuccessfulTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"bitcoinTxId":{"type":["string","null"]},"bitcoinBlockHeight":{"type":["integer","null"],"format":"int64","minimum":0},"bitcoinTxStatus":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BitcoinTxStatus"}]},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}},"StatusSchema":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["queued"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["processed"]}}},{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["failed"]}}}]},"RollbackStatusSchema":{"oneOf":[{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["rolledback"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["notRolledback"]}}}]},"BitcoinTxStatus":{"type":"string","enum":["pending","confirmed","failed","rolled_back"]},"TransactionType":{"type":"string","enum":["open_position","close_position","increase_liquidity","decrease_liquidity","swap","initialize_pool","add_pool_shards","collect_protocol_fees","initialize_protocol","set_owner","toggle_paused","SetFeeTiers"]},"TransactionDetails":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/InitializeProtocolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_protocol"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetOwnerData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_owner"]}}}]},{"allOf":[{"$ref":"#/components/schemas/TogglePausedData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["toggle_paused"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SetFeeTiersData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["set_fee_tiers"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["open_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["increase_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["decrease_liquidity"]}}}]},{"allOf":[{"$ref":"#/components/schemas/PositionData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["close_position"]}}}]},{"allOf":[{"$ref":"#/components/schemas/AddPoolShardsData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["add_pool_shards"]}}}]},{"allOf":[{"$ref":"#/components/schemas/SwapData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["swap"]}}}]},{"allOf":[{"$ref":"#/components/schemas/CollectProtocolFeesData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["collect_protocol_fees"]}}}]},{"allOf":[{"$ref":"#/components/schemas/InitializePoolData"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["initialize_pool"]}}}]}]},"InitializeProtocolData":{"type":"object"},"SetOwnerData":{"type":"object","required":["owner"],"properties":{"owner":{"type":"string"}}},"TogglePausedData":{"type":"object","required":["paused"],"properties":{"paused":{"type":"boolean"}}},"SetFeeTiersData":{"type":"object","required":["feeTiers"],"properties":{"feeTiers":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}},"PositionData":{"type":"object","required":["positionId","token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid","prevTransactions"],"properties":{"positionId":{"type":"string"},"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransactions":{"type":"array","items":{"type":"string"}}}},"AddPoolShardsData":{"type":"object","required":["shards","diffShards","btcFeePaid","totalBtcFeePaid"],"properties":{"shards":{"type":"integer","format":"int32","minimum":0},"diffShards":{"type":"integer","format":"int32","minimum":0},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"SwapData":{"type":"object","required":["amountIn","amountOut","zeroToOne","btcFeePaid","totalBtcFeePaid"],"properties":{"amountIn":{"type":"string"},"amountOut":{"type":"string"},"zeroToOne":{"type":"boolean"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"CollectProtocolFeesData":{"type":"object","required":["token0Amount","token1Amount","btcFeePaid","totalBtcFeePaid"],"properties":{"token0Amount":{"type":"string"},"token1Amount":{"type":"string"},"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0}}},"InitializePoolData":{"type":"object","required":["btcFeePaid","totalBtcFeePaid"],"properties":{"btcFeePaid":{"type":"integer","format":"int64","minimum":0},"totalBtcFeePaid":{"type":"integer","format":"int64","minimum":0},"prevTransaction":{"type":["string","null"]}}},"FailedTransaction":{"type":"object","required":["id","status","rollbackStatus","blockHeight","poolPubkey","userPubkey","transactionType","createdAt","details","writableAccounts"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusSchema"},"rollbackStatus":{"$ref":"#/components/schemas/RollbackStatusSchema"},"blockHeight":{"type":"string"},"poolPubkey":{"type":"string"},"userPubkey":{"type":"string"},"transactionType":{"$ref":"#/components/schemas/TransactionType"},"createdAt":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/TransactionDetails"},"writableAccounts":{"type":"array","items":{"type":"string"}}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}} ``` # Charts ## GET /ohlc > Fetch OHLC (candlestick) data for the requested pair ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"ohlc","description":"OHLC chart data"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/ohlc":{"get":{"tags":["ohlc"],"description":"Fetch OHLC (candlestick) data for the requested pair","operationId":"get_ohlc_data","parameters":[{"name":"granularity","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OHLCGranularity"}},{"name":"startDate","in":"query","required":true,"schema":{"type":"string"}},{"name":"endDate","in":"query","required":true,"schema":{"type":"string"}},{"name":"token0","in":"query","required":true,"schema":{"type":"string"}},{"name":"token1","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OHLC Data","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OHLCData"}}}}},"400":{"description":"Bad request"}}}}},"components":{"schemas":{"OHLCGranularity":{"type":"string","enum":["1m","5m","15m","30m","1h","4h","1d","1w"]},"OHLCData":{"type":"object","required":["id","pair","openPrice","highPrice","lowPrice","closePrice","volume","startTimestamp","endTimestamp","granularity","transactions","createdAt","updatedAt"],"properties":{"id":{"type":"integer","format":"int32","minimum":0},"pair":{"$ref":"#/components/schemas/AssetPair"},"openPrice":{"type":"string"},"highPrice":{"type":"string"},"lowPrice":{"type":"string"},"closePrice":{"type":"string"},"volume":{"type":"string"},"startTimestamp":{"type":"string","format":"date-time"},"endTimestamp":{"type":"string","format":"date-time"},"granularity":{"$ref":"#/components/schemas/OHLCGranularity"},"transactions":{"type":"integer","format":"int32","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AssetPair":{"type":"object","required":["token0Id","token1Id"],"properties":{"token0Id":{"type":"string"},"token1Id":{"type":"string"}}}}}} ``` # Stats ## GET /stats/most-traded > Fetches the rune collection with the biggest volume of trades ```json {"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"stats","description":"Saturn trading statistics"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/stats/most-traded":{"get":{"tags":["stats"],"description":"Fetches the rune collection with the biggest volume of trades","operationId":"get_most_traded_collections","responses":{"200":{"description":"Rune collection with stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionPairStats"}}}},"404":{"description":"No collections found"}}}}},"components":{"schemas":{"CollectionPairStats":{"type":"object","required":["token0","token1","current_price","stats_per_period"],"properties":{"token0":{"$ref":"#/components/schemas/Collection"},"token1":{"$ref":"#/components/schemas/Collection"},"current_price":{"type":"string"},"stats_per_period":{"type":"array","items":{"$ref":"#/components/schemas/CollectionPairStatsForPeriod"}}}},"Collection":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/BTCCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["btc"]}}}]},{"allOf":[{"$ref":"#/components/schemas/RuneCollection"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["rune"]}}}]}]},"BTCCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RuneCollection":{"type":"object","required":["id","name","displayName","divisibility","supply","verified","premined","burned","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"type":["string","null"]},"divisibility":{"type":"integer","format":"int32","minimum":0},"supply":{"type":"string"},"verified":{"type":"boolean"},"icon":{"type":["string","null"]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CollectionPairStatsForPeriod":{"type":"object","required":["period","total_volume","transactions","fee_token0","fee_token1","price_change","high_price","low_price"],"properties":{"period":{"$ref":"#/components/schemas/Period"},"total_volume":{"type":"string"},"transactions":{"type":"integer","format":"int32","minimum":0},"fee_token0":{"type":"string"},"fee_token1":{"type":"string"},"price_change":{"$ref":"#/components/schemas/PriceChange"},"high_price":{"type":"string"},"low_price":{"type":"string"}}},"Period":{"type":"string","enum":["Day","Week","Month"]},"PriceChange":{"type":"object","required":["percentage","absolute"],"properties":{"percentage":{"type":"number","format":"double"},"absolute":{"type":"number","format":"double"}}}}}} ``` # Liquidity Pool SDK Interact with our program using our SDK. Coming soon... # Overview ## General Overview Saturn is the first order book for trading Rare Satoshis, and Rings. For general info on what these are, refer to "[What are Satoshi's, Rare SATs, and Rings](/saturn-v1/faqs/what-are-satoshis-rare-sats-and-rings)" FAQ. ## What can I do on Saturn? #### 1. [Orderbook](/saturn-v1/how-to-links/orderbook) Buy, Sell and Trade Rare Satoshi categories in whatever categories you want. By placing orders/bids or simply buying last price. #### 2 - Discover Easily identify what Rare Satoshis you hold in a wallet and in what quantity. #### 3 - [Collect](/saturn-v1/how-to-links/collect) Collect your Rare Satoshis in a tradeable bundle (UTXO) safely padded to ensure your Rare Satoshis will not be accidentally spent as fees. # How-To-Links
Create a Trading Account/files/y4C3IB2Z3NsN6YoDBrBu/pages/thElIWdFczrjARRpt6UC
The Orderbook/files/zIwvfBDRDJzlOSnzHFCq/pages/bWYBUyQMRvjIgIAdXoND
Tutorial Videos/files/4sRdiogFXQ3rDVvYpVbJ/pages/Ba25fWhccoEyPls4GtyP
Liquidity Provision
# Setting up Trading Account In the new Saturn V3 UI, you will be required to setup a Trading account. Essentially you are depositing the BTC, or Rare SATs that you wish to trade with. {% hint style="info" %} [A full explanation of the changes in V3 ](https://twitter.com/Saturn_btc/status/1740145247366131877) {% endhint %} You have two options (see picture below): 1. **Deposit BTC directly to the Trading account wallet address, by copying it.** This is recommended if there are only small UTXO's present in your wallet or you don't own any Rare SATs or Rings yet, that you want to deposit and trade on Saturn. 2. Click the TOP-up button to deposit BTC already present in your connected wallet
Option 2 (continued) You have clicked "Top up". The window seen below will pop up. Here you have two steps: 1. You select the UTXO you want to deposit. "UTXO" refers to a portion of your wallet containing BTC. The $ value, will indicate how much BTC is present in said UTXO, or portion of your wallet balance. 2. You have to select a Fee rate. This is how many fees you will pay, and how fast your transaction will be completed On-Chain. It is recommended to use Medium, or Fast is the chain is busy.

Depositing UTXO's

Optionally if you already hold any Rare SATs types in your wallet, these will be indicated by their respective ICONS (see below). This way you can easily identify the UTXO's containing rare SATs, if you wish to trade these on Saturn.

In the connected BTC wallet, there is an UTXO present that holds 10.000 Vintage SATs

# Withdrawing from Trading account Click the button featured below to go to your profile. It is found on the top-right of the Saturn website.

Profile button

Clicking this, will open up the window featured below. Click the button that the arrow points to.

Your profile start screen

1. Click Withdraw 2. Select the UTXO you want to withdraw (the $ indicates how much BTC you are withdrawing, and if the UTXO holds any Rare SATs, this will be indicated by their [ICONs](/saturn-v1/faqs/what-are-satoshis-rare-sats-and-rings) 3. Select a fee rate and hit withdraw. 4. The UTXO will now me moved form your Trading Account, back into the BTC wallet you have connected to Saturn

Withdrawing an UTXO

# Swap # Orderbook Buying and selling Rare Satoshis is just a few clicks away!
Saturn is the first live Order Book for Rare Satoshis. Bringing fungibility and collectability to Satoshis that haven't been seen before.\ \ So how do you use it? * [Your Profile](/saturn-v1/how-to-links/orderbook/your-profile) * [How to sell](/saturn-v1/how-to-links/orderbook/how-to-place-a-sell-order) * [How to bu](/saturn-v1/how-to-links/orderbook/how-to-place-a-buy-order)[y](/saturn-v1/how-to-links/orderbook/how-to-place-a-buy-order) * [Positions](/saturn-v1/how-to-links/orderbook/positions) # Your Profile Click the button featured below to go to your profile. It is found on the top-right of the Saturn website.

Profile button

Clicking this, will open up the window featured below:

Your profile start screen

If there are any asset present in your Trading Account, that are tradeable on Saturn, they will show up here. If you don't have any assets in your Trading account, you can use one of two options: You have two options (see picture below): 1. **Deposit BTC directly to the Trading account wallet address, by copying it.** This is recommended if there are only small UTXO's present in your wallet or you don't own any Rare SATs or Rings yet, that you want to deposit and trade on Saturn. 2. Click the TOP-up button to deposit BTC already present in your connected wallet. For more on this option, refer to ["Setting up a trading Account"](/saturn-v1/how-to-links/setting-up-trading-account)
# Trade History Enter your Trade history, under Your Profile, middle tab: * Click the Arrow to view the Status, and more details about the trade * The % next to it, indicates how much of the order is filled.

Trade history

# How to place a sell order ⚠️ Try using a fresh BTC wallet/account designated for trading on Saturn. Saturn will never allow you to spend Rare Sats on fees within the platform. Outside of Saturn however this is not guaranteed. {% hint style="info" %} *You don't have to match the exact quantities within the orderbook, but you do have the match atleast the minimum order size.* ***Minimum order Sizes per Type:***\ The First Transaction, Palindrome, Uncommon: ***1*** \ Nakamoto, Block 78: ***1,000*** \ Pizza, Vintage: ***10,000*** {% endhint %} 1. Navigate to the orderbook using the **LIMIT** tab located at the top of Saturn website.

Use the limit button to navigate to the orderbook.

How to place a sell order

1. Choose the quantity you want to sell: right above this input field, you see your current Balance (how much your wallet holds) 2. Choose the price at which you want to sell. We've chosen a price of 425.000 [Satoshi's ](/saturn-v1/faqs/what-are-satoshis-rare-sats-and-rings)per Uncommon, because if this is the highest buy order on the orderbook (check rightside) 3. Here you see the total value of your order. In this case we are selling 1 uncommon, for 425.000 Satoshi's, so the total order size is 425.000 4. Under 4. You see we have an open sell-order, and this is reflected on the sell-side of the orderbook. 5. Click on "Swap". 6. In the following window, you have to choose your Fee rate. If the Bitcoin network is busy, it is recommended to choose Medium, or Fast.

Choosing a fee rate

7. Click "Sell". Your order is now entered into the Orderbook. If a buy-order at your sell price, is present it gets filled immediately. If there is no buy-order at your sell price, it get's added to the sell-side (top) of the orderbook, as illustrated under point 4. 8. Congratulations! You just sold some Satoshis. # How to place a buy order ⚠️ Try using a fresh BTC wallet/account designated for trading on Saturn. Saturn will never allow you to spend Rare Sats on fees within the platform. Outside of Saturn however this is not guaranteed. {% hint style="info" %} *You don't have to match the exact quantities within the orderbook, but you do have the match atleast the minimum order size.* ***Minimum order Sizes per Type:***\ The First Transaction, Palindrome, Uncommon: ***1*** \ Nakamoto, Block 78: ***1,000*** \ Pizza, Vintage: ***10,000*** {% endhint %} 1. Navigate to the orderbook using the **LIMIT** tab located at the top of Saturn website.

Use the limit button to navigate to the orderbook.

How to place a buy order

1. Choose the quantity you want to **BUY** 2. Choose the price at which you want to sell. We've chosen a price of 65 [Satoshi's ](/saturn-v1/faqs/what-are-satoshis-rare-sats-and-rings)per Nakamoto, because this is the lowest sell order on the orderbook (check rightside). 3. Here you see the total value of your order. In this case we are buying a 1000 Nakamoto's at a price of 65 Satoshi's, so the total order size is 65.000 (1000 x 65). Right above this input field, you can see the balance, or total amount of Satoshi's (BTC) in your wallet. 4. Under 4, you can see the Sell-order in the orderbook, that we are trying to fill with our buy-order. 5. Click on "Swap". 6. In the following window, you have to choose your Fee rate. If the Bitcoin network is busy, it is recommended to choose Medium, or Fast.

Choosing a fee rate

7. Click "BUY". Your order is now entered into the Orderbook. If a sell-order at your buy-price, is present in the orderbook (like in our example) it gets filled immediately. If there is no sell-order at your buy-price, it get's added to the buy-side (bottom) of the orderbook. 8. Congratulations! You just bought some Satoshi's. # Positions At the bottom of the orderbook under the charts, you will find the "Positions" Tab. Here you can see any open orders you have placed, that have not been filled yet. ***You can cancel any open positions for free at any time.***** Costs (including gas fees) are only made, once an order has been accepted.**
To cancel a trade, or to see more info, click the three dots on the rightside
# Collect BTC is stored in what we call [UTXOs](/saturn-v1/faqs/what-is-a-utxo). Your wallet is always comprised of UTXO's, they are "parts" of your wallet. The amount of BTC, or type of Assets a UTXO stores, can vary. In order to safely move around Bitcoin, Rare SATs, or Rings we need to specify which part of our wallet, we want to "collect", or optionally send elsewhere. # Charts
Charts can be found on the Limit view of any asset. Saturn BTC leverages TradingView technology for its market quotes, presenting them through sophisticated charts. This integration offers a broad spectrum of analytical tools for [monitoring cryptocurrency prices](< https://www.tradingview.com/markets/cryptocurrencies/prices-all/>) and accessing the latest market insights. # Tutorial videos The Tutorial Videos cover a range of topics, featured below:
Setting up a Trading Account (v3) and preparing for Rings AirdropsSetting up a Trading Account (v3) and preparing for Rings Airdrops/files/4sRdiogFXQ3rDVvYpVbJhttps://app.gitbook.com/o/5MvUtKzcUNatJYSYVvps/s/edBT5s5MOw7m2x4ZUZp0/~/changes/41/how-to-links/tutorial-videos/setting-up-a-trading-account-v3-and-preparing-for-rings-airdrops
Trading on Saturn/files/zIwvfBDRDJzlOSnzHFCqhttps://app.gitbook.com/o/5MvUtKzcUNatJYSYVvps/s/edBT5s5MOw7m2x4ZUZp0/~/changes/41/how-to-links/tutorial-videos/trading-on-saturn
# Setting up a Trading Account (v3) and preparing for Rings Airdrops {% embed url="" %} Setting up Saturn Rings, by [Fab](https://twitter.com/fabulameo) {% endembed %} {% embed url="" %} @Goodthings with "What is $RUG" {% endembed %} {% embed url="" %} @AmitDhun\_ on how to quallify for the first Rings airdrops {% endembed %} # Trading on Saturn # FAQs
Frequently Asked Questions [What are Satoshi's, Rare SATs, and Rings?](/saturn-v1/faqs/what-are-satoshis-rare-sats-and-rings) [What is a UTXO](/saturn-v1/faqs/what-is-a-utxo) [What is a PSBT](/saturn-v1/faqs/what-is-a-psbt) [Why are there batch sizes](/saturn-v1/faqs/why-are-there-batch-sizes) [Compatible wallets](/saturn-v1/faqs/compatible-wallets)
# What are Satoshi's, Rare SATs, and Rings? ## **Satoshi's** There are 100 million SATs in every Bitcoin. 1 SAT = 0.00000001 BTC. Satoshi's refers to parts of a Bitcoin, like Cents would refer to parts of a Dollar.

Satoshi's to Bitcoin Conversions

## **Special SAT types** These are Satoshi's (small parts of Bitcoin), that were involved in transaction with historical significance (like Pizza), or are special, because of when they we're created (like Uncommon). Refer below for the descriptions of the different types available on Saturn.

Special SAT types on Saturn

## **Rings Token Standard** Rings refers to a new Token-Standard developed by Saturn. The first token that will be released on this standard will be $RUG. Tied to the NFT-community with Ordinals "Bitcoin Rugs". Multiple Ordinal-communities have been selected to be eligble for Airdrops of this new Token Standard. For the full list, check the following channel in the Saturn discord: Early users of Saturn (that deposit a minimum amount of 100K Satoshi's (0.001 BTC) into their [Trading Account](/saturn-v1/how-to-links/setting-up-trading-account), will also be eligble to receive Airdrops of this new Rings Token Standard. {% hint style="info" %} A minimum deposit into a Trading Account on Saturn is required for anyone in the Collaboration Communities, that wants to receive the Rings token Airdrops. Please refer to [Setting up Trading Account](/saturn-v1/how-to-links/setting-up-trading-account) {% endhint %}
https://twitter.com/Saturn_btc/status/1731732672580325705/files/On8LvzoHhTFdhLzobljo
https://twitter.com/ordinalrugs/status/1730282507218665492https://twitter.com/ordinalrugs/status/1730282507218665492/files/ivhfDosBYDmUFJUCKMl9
https://twitter.com/Saturn_btc/status/1730225853076763003https://twitter.com/Saturn_btc/status/1730225853076763003/files/y8LGYjacoG4BPWcEjUsk
https://twitter.com/Saturn_btc/status/1729953439818661956/files/62nxKaIEjfDciG931fht
https://twitter.com/Saturn_btc/status/1730166766628741215/files/b2cpdOX6xQpP1LXfzRv7
https://twitter.com/Saturn_btc/status/1730255231382954090/files/z4w9hNLIcnG4TfLeNp99
https://twitter.com/Saturn_btc/status/1730632221353005132/files/PhxpYnCQiiZCbswmGjpO
https://twitter.com/Saturn_btc/status/1731351539434823881/files/XS6AoUJjlszMuPs1h1aI
https://twitter.com/Saturn_btc/status/1731619371498291588/files/4INZKxbX7fn6iYy5Dho8
https://twitter.com/Saturn_btc/status/1732079490417737870/files/iQhHbumydJb7OlAve08T
https://twitter.com/Saturn_btc/status/1732161561614053631/files/wjhg8MeVDb0XbXEIdnHk
https://twitter.com/Saturn_btc/status/1734233732217770395/files/v2CAC5ZNgz1W1f089SHj
https://twitter.com/Saturn_btc/status/1734933035202543805/files/NYgOwepDZtm9iBFHSrmV
https://twitter.com/Saturn_btc/status/1734966604759220259/files/4vK9yLgXMmNpI6v5CA0U
https://twitter.com/Saturn_btc/status/1735338789315256498/files/3JA5yt3Fc56rHXg1fw7a
# More on Rare SATs What are Rare Satoshis? In order to understand Rare Satoshis we first need to understand what a Satoshi is. #### What is a Satoshi? A Satoshi (sat) is the smallest denomination of Bitcoin. There are 100 million Satoshis in one Bitcoin. Each Satoshi is worth 0.00000001 Bitcoin.
Next to understand what a Rare Satoshi is we need to understand what Ordinal Theory is... #### Ordinal Theory Ordinal Theory essentially assigns Satoshis (the smallest denomination of Bitcoin) with a numismatic value, numbering them in order of creation.\ \ This allows individual Satoshis to be collected and traded as digital artefacts, similar to non-fungible tokens (NFTs) #### Rare Satoshis Thanks to Ordinal Theory, we know exactly which Satoshi is which, when it was made, and how it was used.\ \ This allows us verify historically significant Satoshis to be collected. For example, Pizza Satoshis represent the Satoshis used in the first ever Bitcoin Transaction of 10,000 Bitcoin for two pizzas. Thanks to Ordinals Theory we can identify and verify those Satoshis to be collected. # What is a UTXO In the Bitcoin system, a UTXO stands for "Unspent Transaction Output." Here's what it means in basic terms: 1. **Transaction Outputs:** When a Bitcoin transaction occurs, it creates "outputs." These outputs are amounts of Bitcoin that are designated for specific addresses. Essentially, they represent how the Bitcoin is divided up and where it's sent. 2. **Unspent:** When we say an output is "unspent," it means that the Bitcoin assigned to that output has not been used in a new transaction yet. It's still available to be used by the owner of the associated address. 3. **The UTXO Model:** Bitcoin uses the UTXO model to track ownership and transaction states. Every time you receive Bitcoin, a new UTXO is created, associating that amount with your address. When you send Bitcoin, you are consuming one or more UTXOs and creating new ones. The Bitcoin network checks only the UTXOs (and not any account balance) to validate that you have enough Bitcoin to send in a transaction. 4. **Record Keeping:** Think of UTXOs as individual line entries in Bitcoin's ledger. Instead of each user having a singular balance, Bitcoin's history consists of these UTXOs which, when totaled up, give the balance of an address. In essence, the UTXO model is Bitcoin's way of keeping track of who has how much Bitcoin by maintaining a record of all individual transaction outputs that have not been spent yet. # What is a PSBT A PSBT, or Partially Signed Bitcoin Transaction, is a standardized format for Bitcoin transactions that aren't fully signed yet. It provides a way to work with transactions that might require multiple signatures or other processes before they're finalized and broadcasted to the Bitcoin network.\ \ Thanks to PSBTs we are able to sent orders and bids without the need of a smart contract enabling decentralised P2P order books. # Why are there batch sizes? Batch sizing ensures that the order remains as liquid as possible. \ \ We do large batch sizing to avoid people spending more on transaction fees than the cost of the order/bid.\ \ **What are our Batch standards?** **Palindrome, Uncommon, Block9**: 1 rare sat + 545 common Satoshis for padding. **Block78, Nakamoto:** 1,000 Rare Satoshis without padding. **Vintage, Pizza**: 10,000 Rare Satoshis without padding # Compatible Wallets Unisat\ \ Twitter - \ \ Xverse \ \ Twitter - {% hint style="info" %} Xverse currently does not support multiple signings of PSBTs therefore in order to increase usability we recommend to use Unisat when transacting on Saturn. {% endhint %} # Why is my Available balance different than my Total balance? There are a few reasons why your Available balance is different than your Total balance. First, lets break down what each of them represent.\ \ **Total balance**: The total amount of an asset within your wallet.\ \ **Available balance**: The amount of that asset that is available to be used for trading or withdrawing. As you deposit, withdraw, collect, buy, sell, or receive airdrops, these balances will continuously change.\ \ The most common reason why your Available balance might be lower than your Total balance, or even 0, is because you have an open position, or pending order. ### How to Check Open Positions You can check on your open positions within the Positions widget on the Limit tab:
While this position is open, any assets involved in the order are removed from your Available balance until the position is cancelled or processed.\ \ Cancelling a position with 0% filled will make any assets involved available again under Available balance immediately. Cancelling a position partially filled, will process the order at that partially filled amount. Your balances won't update until that order is broadcasted and confirmed. ### How to Check Pending Orders You can check on your Pending Orders by opening up the History tab of your Trading Wallet:
Just because your order is Filled, it does not mean it's completed. It could still be pending. Click on the icon next to your order to check the status.\ \ If your status is Pending to Broadcast, Transaction to be Broadcasted, or Pending Confirmation, your order is still pending and your Available balance will not yet be updated.\ \ If your status is Confirmed, the order is fully completed and your Available balance will be updated. ### UTXO's with More than One Asset Type Another reason your Available balance might be lower than your Total balance, or even 0, is because there's more than one asset within the same UTXO. This is likely the culprit if you don't have any open positions, or pending orders and still seeing a discrepancy between your Total and Available balances.\ \ This is usually the result of a recent airdrop to your wallet or how the UTXO was when you deposited. #### Airdrops When your wallet receives an airdrop, the airdropped tokens are dropped into an existing UTXO. If you have a UTXO with 100,000 Common Sats and receive an airdrop of 2000 RUG, the UTXO is updated to 98,000 Common Sats and 2000 RUG. Afterwards, your 2000 RUG will show under Available balance and can be traded right away. The 98,000 Common Sats within that UTXO are removed from your Available balance and will only display under your Total balance.
If you had more than 1 UTXO during the airdrop, the other UTXO's with Common Sats will continue to show under Available balance. Only the UTXO that the airdrop was added to has the Common Sats made unavailable. In order to make those Common Sats available again, you would need to split the UTXO into two UTXO's. One with just Common Sats and one with just RUG. You can use the Collect tool to do this. #### Deposits When depositing UTXO's, some contain just Common Sats, while others contain Rare Sats or Rings tokens on their own or mixed in with Common Sats (yellow box in the screenshot below shows a UTXO with both a Palindrome Sat and Common Sats)
In this example, depositing the UTXO with the Palindrome Sat will result in 1 Palindrome Sat displaying under Available balance. This can be traded right after it's deposited. However, the Common Sats within that UTXO will only display under Total balance. Since they're within the same UTXO as a Rare Sat (or Rings token), they're not available to be used for trading and will not show under Available balance.
In the example above, the wallet has 1 Palindrome Sat with 327,221 Common Sats within the same UTXO. The 1 Palindrome Sat is available, while the 327,221 Common Sats are only showing under Total and not available to be used for trading. In order to make those Common Sats available again, you would need to split the UTXO into two UTXO's. One with just Common Sats and one with the Palindrome Sat (and minimum padding) . You can use the Collect tool to do this.