# What is Sats Terminal
Sats Terminal is an intuitive interface for trading, borrowing, and earning with Bitcoin. The platform brings together different tools and services so users can swap assets, borrow stablecoins using BTC as collateral, and earn yield on BTC or stablecoins. *** {% stepper %} {% step %} #### **Trade** Swap Bitcoin L1 and L2 assets. Trades are routed across available liquidity sources to find the best available price. Learn more about Trade {% endstep %} {% step %} #### **Borrow** Borrow stablecoins using your Bitcoin as collateral through our cross-chain loans aggregator. Sats Terminal compares loan offers from multiple lenders and picks the option with the best terms for the users Learn more about Borrow {% endstep %} {% step %} #### **Earn** Earn yield on BTC and stablecoins through our native and partner vaults. Learn more about Earn \
{% endstep %} {% endstepper %} # Why Sats Terminal
1. Bitcoin-Native by Design No need to bridge or wrap your BTC to get a loan or earn Bitcoin yield All products are native-Bitcoin only
2. Fast Execution & Optimized Routing Sats Terminal delivers speed where it matters: * Fast Runes and Spark swaps * Smart routing across multiple liquidity sources * Minimal slippage * Low execution costs Users benefit from fast, predictable transactions, while developers can build applications that respond quickly even under high demand.
3. Secure Infrastructure Security is fundamental in Bitcoin-native finance.\ Sats Terminal uses a multi-layered approach: * Hardened APIs and infrastructure * Robust operational monitoring * Secure collateral management for BTC loans This ensures that traders, developers, and borrowers interact with Sats Terminal products confidently and safely.
4. Developer-First Tools Sats Terminal provides one of the most complete toolkits for building on Runes and Spark: * **Runes SDK** – integrate swaps directly into apps, wallets, or dashboards * **Clear API documentation** – endpoints, parameters, examples * **Simple onboarding** – ready-to-use code samples and quickstart guides Developers spend less time dealing with infrastructure and more time building innovative products.
5. Unified Ecosystem of Products Instead of fragmented tools, Sats Terminal offers everything in one place: * **Runes Swap** – instant token swaps * **Spark Swap** – high-performance Spark-based swaps * **Runes SDK** – integration toolkit for builders * **Borrow BTC Loans** – collateralized BTC borrowing This makes Sats Terminal a central hub for Bitcoin-native DeFi - suitable for traders, platforms, and developers alike.
6. Simple, User-Friendly Experience Sats Terminal is built for mainstream adoption, not just experts.\ Every product is designed with clarity and simplicity: * Clean swap interface * Straightforward loan management * Easy wallet connections * Transparent flows New users can onboard quickly, while advanced users still enjoy deep control and customization.
7. Built for the Future of Bitcoin Bitcoin’s ecosystem is evolving fast:\ Runes, Spark, L2s, tokenization, BTC-backed credit markets - all of these require reliable infrastructure. Sats Terminal aims to become the foundation for this new Bitcoin-native financial stack. We build for: * Scalability * Composability * Multi-product interoperability * Long-term sustainability Sats Terminal isn’t just keeping up with the Bitcoin ecosystem - it’s helping shape it.
Sats Terminal is the best choice for users and developers who want: * True Bitcoin-native products * Fast and secure swaps * Powerful developer tools * Reliable borrowing mechanisms * A unified ecosystem that keeps growing Bitcoin is entering a new era - and Sats Terminal is one of the platforms leading the way forward. # Quick Links Direct access to the most important resources in the ecosystem.
Cover image
Developer Docs/files/UK7ofimR23bykeakfDvOhttps://developer.satsterminal.com/overview
Our Blog/files/UK7ofimR23bykeakfDvOhttps://www.satsterminal.com/blog
Join Our Community/files/UK7ofimR23bykeakfDvO/pages/MfaIKjNk9irfYdVZtYLT
# Borrow by Sats Terminal Borrow is a cross-chain loans aggregator that lets users borrow stablecoins using Bitcoin as collateral at the best available rate Instead of manually checking Aave, Morpho, or centralized desks, Borrow automatically compares the entire market and executes the loan through the optimal route - **fully non-custodially**, using only the user’s Bitcoin wallet.
## Core Value Proposition {% stepper %} {% step %} **Borrow stablecoins using BTC as collateral** {% endstep %} {% step %} **Best available rates** across multiple decentralized lending protocols {% endstep %} {% step %} **No KYC** - login with email {% endstep %} {% step %} **Self-custody** powered by Privy {% endstep %} {% step %} **Automated bridging, wrapping, and protocol execution** {% endstep %} {% step %} **20–30 minute** to get end-to-end loan {% endstep %} {% endstepper %} # Trade by Sats Terminal Trade by Sats Terminal aggregates liquidity across AMMs, order books to deliver best execution for Bitcoin L1 & L2 assets trading ## Overview Trading Bitcoin L1 assets (like Runes) has always been fragmented: dozens of DEXs, inconsistent liquidity, volatile pricing, slow UX, and large execution slippage. \ Sats Terminal solves this by unifying all liquidity sources under a single, fast, non-custodial interface. With advanced routing algorithms and real-time market intelligence, the Trade module ensures your swaps always follow the most optimal path - whether that means routing through multiple pools, crossing order books, splitting orders, or using hybrid liquidity sources. *** ## Runes Swap **Sats Terminal Runes Swap** is the first **Bitcoin-native aggregation protocol** designed to get you the **best execution on every Runes swap**. \ Instead of routing trades through a single DEX, Sats Terminal aggregates liquidity across multiple Bitcoin decentralized exchanges, marketplaces, and DeFi platforms — ensuring optimal pricing, minimal slippage, and reliable settlement. #### **Key Features** * Best-execution routing across multiple Bitcoin DEXes * Aggregated liquidity for deeper markets * Lower slippage, better pricing, higher reliability * One integration for all supported Runes swap sources * Built for developers, wallets, and applications #### **Integrations** * **Swap v2 SDK** for programmatic trading and custom UI * **Swap API (Coming Soon)** for deep backend integrations * **Sats Terminal Embed** for instant, no-code swap interfaces *** ## Runes SDK The **Swap v2 SDK** is the fastest way to integrate Bitcoin-native swaps into any product. \ Written in JavaScript/TypeScript, it works in both **front-end** and **back-end** environments and handles all communication with Sats Terminal’s smart routing engine. Use it to build: * Your own custom swap experience * Automated trading scripts * Wallet integrations * Backend swap services #### **Key Features** * Smart routing logic handled automatically * Built-in error handling and transaction management * Fully compatible with all Bitcoin-native wallets * Light and flexible for any architecture * Works with Node.js, browsers, and serverless functions #### **Best For** > Developers who want full control over the swap UX/UI or need to build complex integrations without maintaining routing logic themselves. *** ## Spark Swap **Spark Swap** brings Lightning-fast Bitcoin L2 swaps into the Sats Terminal ecosystem. #### **Key Features** * Instant, low-fee swaps * Bitcoin-native security * Seamless integration through the Sats Terminal * Unified interface with the Runes Swap aggregator * Designed for next-generation Bitcoin L2 applications # Runes SDK SDK that lets developers integrate Runes swaps directly into their dApps, wallets, or services. The **Swap v2 SDK** is the fastest way to integrate Bitcoin-native swaps into any product.\ Written in JavaScript/TypeScript, it works in both **front-end** and **back-end** environments and handles all communication with Sats Terminal’s smart routing engine. Use it to build: * Your own custom swap experience * Automated trading scripts * Wallet integrations * Backend swap services #### **Key Features** * Smart routing logic handled automatically * Built-in error handling and transaction management * Fully compatible with all Bitcoin-native wallets * Light and flexible for any architecture * Works with Node.js, browsers, and serverless functions #### **Best For** > Developers who want full control over the swap UX/UI or need to build complex integrations without maintaining routing logic themselves. # Spark Swap A high-performance swap system connected to the Spark ecosystem, enabling quick and cost-efficient token swaps on Bitcoin. **Spark Swap** brings Lightning-fast Bitcoin L2 swaps into the Sats Terminal ecosystem.\ Built around the Spark protocol, it enables low-fee, scalable, Bitcoin-secured swaps and opens a new category of high-speed Bitcoin DeFi integrations. #### **Key Features** * Instant, low-fee swaps * Bitcoin-native security * Seamless integration through Sats Terminal * Unified interface with the Runes Swap aggregator * Designed for next-generation Bitcoin L2 applications # Earn by Sats Terminal {% hint style="warning" %} Coming Soon {% endhint %} # Official Links Join the Sats Terminal community across platforms: Telegram, Twitter, Discord, and other social channels. {% hint style="success" %} The links on this page are the official links associated with Sats Terminal. Please be vigilant and check that the URL matches exactly. {% endhint %}
Cover image
:browser:

Website

https://www.satsterminal.com/https://www.satsterminal.com/
:x-twitter:

X (Twitter)

https://x.com/satsterminal
:discord:

Discord

https://discord.com/invite/khkddgzwcX
:telegram:

Telegram

https://t.me/SatsTerminal
# Blog / Announcements Stay updated with the latest releases, feature updates, ecosystem news, and important announcements from Sats Terminal.
Cover image
:calendar: November 18, 2025

Putting Bitcoin to Work - Episode 5: Who Holds Your Bitcoin?

/files/sqzkvYZ6sYEauv98naPG/pages/iYtGEDueyaCaqkXU6jzA
:calendar: November 10, 2025

Putting Bitcoin to Work - Episode 4: Avoiding Liquidation

/files/ccOZ5159tFp3ElIt14dh/pages/A20AFivt5t59JzAi1054
# Putting Bitcoin to Work - Episode 5: Who Holds Your Bitcoin? When you borrow against your bitcoin, one question matters more than most: Who actually controls your coins while the loan is active? Many borrowers focus on LTVs, interest rates, or terms. But custody—who holds your bitcoin and how—determines your real security and risk exposure. In this post, we’ll break down what custody means, how it works in CeFi and DeFi, and what to look for before you borrow. *** > ### TL;DR > > * Custody = who controls your bitcoin while your loan is active. > * CeFi = custodial: your BTC sits with the lender or a custodian. > * DeFi = smart-contract custody: your BTC is held by code, not a company. > * Each path carries different risks: operational, smart-contract, governance, and rehypothecation. > * Always ask: *Can anyone move my bitcoin without my permission?* *** ### Why custody is the “invisible risk” most borrowers ignore A bitcoin loan sounds simple: deposit BTC, get stablecoins, repay later. But once you send that BTC, control shifts. And depending on the custody model, that shift could be minimal, or absolute. Custody defines your rights: * Can you withdraw anytime? * Could your funds be frozen? * Is your BTC rehypothecated (reused by the lender)? Understanding custody is the difference between *owning bitcoin* and *hoping you’ll get it back.* ### CeFi custody: trust, regulation, and operational risk In centralized finance (CeFi), your BTC is handed to a company or its custodian (e.g., BitGo or Fireblocks). They hold the keys. Not you. **Pros:** * Regulated structure and customer support. * Familiar process and fixed-rate terms. **Cons:** * You lose direct control of your BTC. * The platform can freeze withdrawals or reuse collateral. * Transparency is limited. You can’t verify balances on-chain. CeFi custody is convenient, but it’s trust-based. You’re counting on the provider’s integrity and solvency. ### DeFi custody: code holds your collateral, not a company DeFi custody removes the middleman. Your bitcoin (often wrapped) is held by smart contracts that enforce rules automatically: collateralization, liquidation, repayment. **Pros:** * Transparent, on-chain logic. * No company controlling your coins. * Accessible 24/7, permissionless. **Cons:** * Smart contract vulnerabilities can lead to loss. * Bridges used to wrap BTC can fail or be hacked. * Governance structures may still hide admin controls. In DeFi, you replace *human trust* with *code trust.* It’s a trade-off, but one you can inspect directly on-chain. ### True DeFi: Full self-custody until the end True DeFi pushes things further. No admin keys, no manual overrides, no opaque governance. You interact directly from your wallet, and no one can touch your bitcoin until liquidation conditions are met. It’s the cleanest model for transparency and control, but also requires personal responsibility. You’re your own bank. And that means your own safety net, too. ### Rehypothecation: the hidden clause borrowers never read Rehypothecation happens when your lender reuses your collateral elsewhere. It’s a common practice in traditional finance and some CeFi lending models. That reuse can generate yield for the platform, but it exposes your bitcoin to extra layers of risk. If a downstream counterparty fails, your collateral could be gone even if your original lender survives. In DeFi, rehypothecation is rare, but it can exist through pooled or leveraged structures. Always check for clear disclosures or on-chain traceability before depositing. ### Governance risk: who controls the system? Even in DeFi, someone controls the levers: * admin keys * upgrade paths * pause functions * emergency controls A platform might be non-custodial today… …but that can change if governance isn’t transparent. Good platforms clearly show whether keys exist, who holds them, and what they can do. ### What to check before you borrow **1. Who physically or programmatically holds your collateral?** * CeFi = custodian. * DeFi = smart contract. **2. Can your BTC be rehypothecated?** * If yes, risk increases. **3. Are there independent audits or proof-of-reserves?** * The more visibility, the better. **4. What can admin or governance keys do?** * Pause withdrawals? * Upgrade contracts? * Move collateral? A few minutes of due diligence can save years of regret. *** ### FAQs **Is custodial always bad?**\ No. Some borrowers prefer regulated CeFi lenders for convenience and support. The key is knowing the trade-off: security and control vs simplicity and structure. **How can I tell if a platform is non-custodial?**\ You connect your wallet, interact on-chain, and can verify your position publicly. If someone else holds your BTC or can pause your account, it’s custodial. **What’s rehypothecation in plain English?**\ It’s when your lender uses your collateral for their own purposes, like lending your car to someone else while it’s still under your name. *** ### Borrow with clarity Ready to borrow with full transparency? Compare CeFi and DeFi loan providers side-by-side (custody, rates, LTVs, and risk signals) all in one place. Borrow your way. Visit Borrow by Sats Terminal today: [borrow.satsterminal.com/](https://borrow.satsterminal.com/) # Putting Bitcoin to Work - Episode 4: Avoiding Liquidation Borrowing against your bitcoin can unlock liquidity without selling your stack, but it can also introduce risk. Markets move fast, and if you’re not paying attention, your collateral can vanish just as quickly. In this post, we break down how to manage risk, avoid liquidation, and borrow smarter, whether you’re using CeFi or DeFi platforms. ### TL;DR * Every bitcoin loan carries risk. Liquidation, custody, interest rate, and stablecoin risk. * Keep your Loan-to-Value (LTV) ratio conservative (20–35%). * Know who holds your bitcoin; a custodian or a smart contract. * Watch for variable rate spikes and stablecoin depegs. * Borrow less than you can, and automate where possible. ### 1. Liquidation risk: the one that sneaks up on you This is the biggest risk when borrowing against bitcoin. If bitcoin’s price drops and your LTV rises above a set threshold, your lender can liquidate your collateral to cover the loan. **Example:** You borrow $5,000 against 0.5 BTC when BTC = $25,000. That’s a 40% LTV. If BTC drops to $20,000, your LTV rises to 50%, reducing your buffer. At that point, you’re getting closer to common liquidation thresholds. Maybe not an emergency, but a signal to stay alert, review your loan’s health, and consider whether you need to add collateral or repay part of the loan before market moves force your hand. **How to manage it:** * Borrow at a conservative LTV (20–35%). * Keep a small stablecoin reserve for quick top-ups. * Monitor your loan’s health factor, especially if your loan has variable rates. Liquidation risk can creep in like a rising tide. Slow, steady, and easy to ignore until it’s too late. ### 2. Custody and counterparty risk Always ask: Who actually holds my bitcoin? * CeFi loans: Your BTC sits with a custodian (like BitGo). You’re trusting the company not to freeze, rehypothecate, or mismanage collateral. * DeFi loans: Your BTC is locked in a smart contract. No middleman, but you’re trusting code, which can fail or be exploited. **Smart approach:** * Prefer platforms with Proof of Reserves or on-chain audits. * Check how admin keys and governance controls work. * Understand if collateral is pooled, reused, or segregated. Trust is replaced by transparency. Make sure you can actually *see* what’s happening behind the scenes. ### 3. Interest rate and liquidity risk Fixed-rate loans are predictable, but variable rates can change fast. When market liquidity dries up, interest rates can jump, and your cost of borrowing climbs with it. **Tip:** Before you borrow, run a quick stress test: \> What happens if your rate doubles? \> Can you still afford repayments if BTC dips at the same time? If not, scale back your LTV before signing. It’s always easier to increase leverage later than to unwind it in a panic. ### 4. Stablecoin and peg risk Most loans are paid out in stablecoins like USDC, USDT, or DAI. They’re designed to stay at $1, but not all are equal. * **USDC:** regulated and fully backed, but can freeze addresses. * **DAI:** decentralized, but partly backed by USDC. * **USDT:** widely used and liquid, with different reserve reporting standards. If a stablecoin loses its peg, you could owe more in real terms or face delays withdrawing funds. Always check which stablecoin your loan uses and how it maintains stability. ### 5. Platform reputation and transparency A big name can feel safer, and sometimes it is. Reputable, regulated platforms often have deeper liquidity, stronger compliance, and more resources to manage risk. But reputation isn’t a guarantee. Even big names can fail. Look for: * Audited code or published Proof-of-Reserves. * Visible risk metrics like utilization, TVL, and liquidation ratios. * Clear governance structures, not hidden admin control. At Sats Terminal, we surface these details directly in our interface—custody type, governance, rehypothecation, and rate history—so you can compare lenders with facts, not assumptions. ### FAQs **What’s a conservative LTV to borrow at?** Typically 20–35%. It gives you breathing room if the market dips. **Can I lose my bitcoin in a loan?** Yes. If your LTV exceeds the liquidation threshold and you don’t top up in time, your collateral can be sold automatically. **How can I avoid surprise liquidations?** Use alerts or auto-top-up. Keep extra stablecoins handy to rebalance quickly. ### Borrow smart, stay safe Putting your bitcoin to work doesn’t mean putting it at risk. A well-managed loan can unlock liquidity, fund new opportunities, and even help you stack more sats. But only if you understand the downside. Borrow with a margin of safety, not a margin of error. At Sats Terminal, our goal is to make that easier, with full visibility into custody, collateral, and risk, all in one place. Borrow smarter. Stay liquid. Keep your keys. Visit [Borrow](https://borrow.satsterminal.com/) at Sats Terminal today. # What is Borrow ### Overview Borrow by Sats Terminal allows users to borrow stablecoins, such as USDC, using bitcoin as collateral. The platform automatically compares loan offers from supported lenders and returns the most competitive loan terms available. Bridging and wrapping steps are handled automatically where required, keeping the experience straightforward for BTC users.
### **Key Features** * Non-custodial BTC collateral flow * Access to a range of supported DeFi and CeFi lenders * Always finds the best rates across available loan providers at the time of request * Borrowing with native BTC # Why Use Borrow Borrow by Sats Terminal provides a simple way to access stablecoins using bitcoin as collateral. The platform aggregates supported lenders and returns the most competitive loan terms currently available, allowing users to choose a loan without manually comparing providers.
### **Key Advantages** {% stepper %} {% step %} #### **Best Rates, Automatically** Borrow reviews supported CeFi and DeFi lenders and shows the most competitive terms available at the time of your request. {% endstep %} {% step %} #### **No Middlemen, No KYC** Users can sign up with an email address. Borrow operates without requiring personal identification. {% endstep %} {% step %} #### Automated Cross-Chain Steps If lending providers operate on different chains, Borrow guides the user through the required steps. Bridging and wrapping are handled in-flow where applicable. {% endstep %} {% step %} #### Speed & simplicity From requesting a quote to receiving stablecoins, the process is designed to be simple and intuitive. {% endstep %} {% step %} #### Self-Custody Users manage their assets through a Privy-backed wallet model, meaning collateral is never held in a conventional custodial account. {% endstep %} {% endstepper %} ### Technology and Integrations * **Privy-powered wallets** secure millions of accounts and billions in transactions. * Borrow works with established lending providers and infrastructure components used widely across the ecosystem. This includes Privy for secure wallet interaction and supported lenders such as Aave or Morpho. *** # How Borrow Works Borrow by Sats Terminal allows users to access stablecoins by using bitcoin as collateral. The process is designed to be simple and straightforward, with the platform handling the more complex steps in the background. #### 1. Registration & Wallet Setup Users begin by signing up with an email address. No KYC or personal identification is required. When signing in: * A self-custodial wallet is created for the user. * The wallet is secured through Privy’s authentication system, which allows users to access their assets without managing private keys directly. * The wallet can authorize certain automated actions (such as supplying collateral) while ensuring the user remains in full control. This setup allows users to borrow against BTC without installing a separate wallet or managing seed phrases. #### 2. Loan Configuration Users choose how much BTC they want to use as collateral or how much stablecoin they want to borrow. Borrow then checks supported lending providers and displays the loan options currently available. Each loan option includes: * the estimated interest rate * any associated fees * the amount of stablecoins the user will receive * the required collateral and LTV After reviewing the available choices, the user selects the option that best suits their needs. {% hint style="success" %} Example: A user may choose to borrow 50% of the value of the BTC they deposit as collateral giving them a 50% LTV. {% endhint %} #### 3. Deposit Bitcoin Borrow provides a unique Bitcoin address for the user’s collateral deposit. The user sends BTC to this address directly from their own wallet. After the transaction is submitted for confirmation on the Bitcoin network, Borrow waits for the required confirmations before continuing the process automatically. The system tracks confirmations in real time to ensure secure processing. At each stage, the app provides transparency so users can track the status of their collateral. #### 4. Processing Collateral (Handled Automatically) After the BTC deposit is confirmed, Borrow handles the required steps to prepare the collateral for the selected loan. This may include: * moving the BTC to the network used by the lending provider * supplying the collateral to that provider * initiating the stablecoin loan All of these actions happen automatically in the background. The user does not need to manage wrapping, bridging, or smart contract interactions themselves. Once the collateral is supplied, the stablecoins are issued to the user’s wallet. #### 5. Receive Stablecoins Once the collateral has been supplied to the lending provider, the borrowed stablecoins are sent to the user’s self-custodial wallet. From there, users can: * hold their stablecoins, * send them to another wallet and/or off-ramp to fiat, or * use them within supported products on the platform. The stablecoins remain fully controlled by the user at all times. # Creating Your Account A step-by-step guide to creating your Borrow account and setting up a secure, self-custodial wallet effortlessly.
Step 1 - Sign Up * Users register with an email address * Verification is completed via a secure email link * No KYC or personal information is required
Step 2 - Wallet Setup * A self-custodial Privy wallet is created automatically * Users do not need to manage private keys or seed phrases * The wallet is used to hold collateral and loan assets
Step 3 - Permissions for Borrowing * To complete a loan, the wallet may request permission to perform specific actions * These permissions are secure and limited and can be reviewed by the user * The user remains in control of their assets at all times
*** # Taking Your First Loan Step-by-step guidance for borrowing stablecoins using your Bitcoin as collateral, fully automated and non-custodial. This guide walks you through the steps of borrowing stablecoins using bitcoin as collateral. Each stage is designed to be clear and straightforward, with Borrow handling the technical work in the background. {% stepper %} {% step %} #### Set your loan preferences Start by choosing how you want to structure your loan: * enter the amount of BTC you want to use as collateral, * or enter the amount of stablecoins you want to borrow. Borrow will calculate the corresponding Loan-to-Value (LTV) and show how much collateral is required. You can adjust the amounts until the LTV matches your preference. This helps you understand the trade-off between collateral, borrowing amount, and risk before moving forward. {% endstep %} {% step %} #### Review the available loan offer After you set your loan preferences, Borrow checks supported lending providers and displays all available loans based on the terms. Information includes: * the estimated interest rate * any fees associated with the loan * Max LTV * liquidation price * collateral details This allows you to review the terms and select the option that best suits your needs before moving forward. {% endstep %} {% step %} #### Deposit your Bitcoin Borrow generates a unique Bitcoin address for your collateral deposit. You send BTC to this address from your own wallet. After the transaction is submitted, Borrow waits for the required confirmations on the Bitcoin network before continuing. You can track the deposit status in real time while it completes. Your BTC remains in a self-custodial flow until it is supplied to the lender you select. If you choose a custodial lender, the collateral will be held by that provider as part of the loan. {% endstep %} {% step %} #### Borrow prepares the collateral After your BTC deposit is confirmed, Borrow handles the steps required to prepare the collateral for the lender you select. This may involve moving the BTC to the network used by that lender and supplying it as collateral on your behalf. Throughout this process: * You approve the actions before they occur * Borrow only performs the steps needed to complete the loan * You can track the progress directly in the app If you choose a custodial lender, the collateral will be held by that provider as part of the loan. For non-custodial lenders, the collateral remains in a self-custodial flow until supplied to the protocol. {% endstep %} {% step %} #### Receive your stablecoins Once the collateral has been supplied to the lending provider, the borrowed stablecoins are sent to the user’s self-custodial wallet. From there, users can: * hold their stablecoins, * send them to another wallet and/or off-ramp to fiat, or * use them within supported products on the platform. {% endstep %} {% endstepper %} # Using Borrowed Stablecoins How to effectively manage, spend, and off-ramp the stablecoins borrowed through Borrow. #### Immediate Access * Once your USDC loan is delivered to your **Privy wallet**, you have **full control** over the funds. * Funds are available instantly for **holding, trading, or sending** to any compatible wallet. *** #### Spending & Transfers * Send USDC to friends, merchants, or other wallets with **low transaction fees**. * Use stablecoins for online purchases, crypto trading, or DeFi investments. * All transactions remain **fully self-custodial**, giving you peace of mind. *** #### Off-Ramping to Fiat * Easily convert USDC to fiat. * Off-ramping is **secure and fast**, with funds reaching your bank or card in a few minutes. *** #### Future Features * In-app **investing**, **swaps**, and **yield vaults** for USDC and other supported assets. * Options to **automate payments or portfolio allocation** directly from your borrowed funds. * Borrowed stablecoins can act as a **leveraged position** for additional yield strategies. *** #### Summary Borrowed stablecoins are designed for **flexibility, speed, and full user control**, letting you maximize the utility of your Bitcoin-backed loan without sacrificing security. # Repaying Your Loan Step-by-step guide for full or partial repayment of BTC-backed loans. ### **Overview** Repayment is simple and flexible. You can repay the full loan at once or make partial payments over time. #### **Steps:** {% stepper %} {% step %} Open your loan dashboard. {% endstep %} {% step %} Click **Repay Loan**. {% endstep %} {% step %} Enter the amount to repay (partial or full). {% endstep %} {% step %} Confirm the transaction. Stablecoins are deducted from your wallet. {% endstep %} {% step %} Once repayment is complete, BTC collateral is released back to your wallet. {% endstep %} {% endstepper %} #### **Key Features:** * **Partial repayment:** Reduce interest accrual over time. * **Full repayment:** Unlock full BTC collateral immediately. * **Automated process:** Platform handles unwrapping and bridging of BTC back to your wallet. # Custody & Control Borrow is designed to give users a clear and predictable custody experience. You use a self-custodial wallet, approve each required action, and retain visibility and control throughout the borrowing process. #### Self-custodial wallet When you sign up with your email, a self-custodial wallet is created for you on Sats Terminal. * No KYC is required to create an account * No passwords or seed phrases to manage * Your assets are held in your own wallet * Borrow cannot move funds without your approval This wallet holds your BTC, stablecoins, and any other supported assets used during the loan process. *** #### Email-based authentication Borrow uses simple, passwordless authentication: 1. Enter your email 2. Receive a one-time verification code 3. Enter the code to sign in *** #### Approvals & permissions Some steps in the loan process require Borrow to perform specific actions on your behalf. Before these actions occur, you will be asked to approve the required permissions. * Permissions are limited to the operations needed for your selected loan * Borrow cannot execute transactions without your explicit approval * You can review and manage permissions from your wallet interface Borrow only executes the actions you explicitly approve. *** ### Custody during the loan The custody of your BTC collateral depends on the lender you choose: #### Non-custodial lenders Collateral is supplied to a smart-contract-based protocol. These flows follow on-chain logic and do not rely on a centralized custodian. #### Custodial lenders Some lenders operate custodially. In these cases, your collateral is held by the lender as part of the loan agreement. Borrow clearly indicates the lender type so you can make an informed decision before proceeding. *** ### Visibility and control Throughout the borrowing journey: * You can track the status of each step * No actions occur without your approval * You maintain control over your wallet and all non-collateral assets * You can repay or manage your loan according to the lender’s terms This structure ensures that you always understand how your assets are handled and what permissions are being used at each stage of the borrowing process. \
# Automation & Permissions Borrow automates the technical steps involved in completing a bitcoin-backed loan so you do not need to manage multiple wallets, networks, or smart-contract interactions yourself. These automated steps always require your explicit approval. #### What Borrow automates To complete a loan, Borrow may automate certain operational tasks such as: * preparing your BTC collateral for the selected lender * supplying the collateral on your behalf * delivering stablecoins to your wallet once the loan is finalized These steps are shown clearly as they occur. *** #### Permissions you approve Before Borrow performs an automated step, you will be asked to approve the specific action. These permissions: * apply only to the loan you have chosen * do not allow Borrow to access unrelated assets in your wallet Borrow cannot execute any action without your confirmation. *** #### What Borrow cannot do There are important limits to what Borrow is able to access or automate: * Borrow cannot withdraw assets from your wallet outside the approved loan operations * Borrow cannot alter your collateral or loan terms without your involvement * Borrow cannot access personal information beyond your email address * Borrow cannot intervene in a loan held by a custodial lender All actions rely on user approval and lender rules. *** #### Visibility and transparency Throughout the process, the Borrow interface shows: * which step is being performed * what action is about to occur * when a permission is required * when collateral has been supplied and when stablecoins have arrived This ensures you always understand what is happening behind the scenes. # Lender & Counterparty Risk Borrow connects users to a range of lenders. Each lender operates under its own custody model, risk profile, and terms. Understanding these differences helps you choose the loan option that fits your needs. ### Non-custodial lenders Some lenders use smart-contract-based systems to manage collateral and issue loans. With these lenders: * collateral is supplied to the protocol’s smart contracts * loan terms are enforced on-chain * repayment, interest, and liquidation follow protocol-defined rules #### Considerations Non-custodial lending carries technical and market risks, including: * smart-contract vulnerabilities * liquidity constraints * protocol-specific parameters such as interest models or liquidation thresholds While these systems are transparent and on-chain, they still involve inherent risks. ### Custodial lenders Other lenders operate using a custodial model. In these cases, collateral is held directly by the lender as part of the loan agreement. #### Considerations Custodial lending introduces counterparty risk: * collateral safety depends on the lender’s operational practices and solvency * loan terms and servicing follow the lender’s internal policies * the lender decides how collateral is managed and stored Custodial providers may offer different rates or features, but users should evaluate the risks that come with centralized custody. ### How Borrow presents lenders Borrow does not hold collateral on behalf of users. Instead, it provides access to supported lenders and clearly shows whether a lender is: * custodial * non-custodial * operating on a specific network * offering a particular loan structure or LTV This transparency allows you to choose a lender based on your own preferences, risk tolerance, and desired loan features. ### Your responsibility as a borrower Before entering a loan, users should consider: * the lender’s custody model * the loan terms and repayment conditions * the risks associated with the type of lender selected * how borrowing decisions may be affected by market volatility Borrow provides the information needed to make an informed decision, but the choice of lender and loan structure ultimately rests with the user. \
# Protocol & Network Risk Borrow interacts with on-chain systems and, in some cases, multiple blockchain networks depending on the lender you select. These systems carry distinct risks and operational considerations that are important to understand. ### Bridging between networks Some lenders operate on networks outside the Bitcoin blockchain. When a loan requires collateral to be used on another network, Borrow may bridge assets as part of the process. Bridging introduces certain considerations: * it relies on infrastructure that connects different blockchain networks * network delays or congestion may affect processing times * all bridging systems carry inherent technical risk, including potential vulnerabilities Borrow only performs bridging when required for the loan you choose. Bridging steps are presented clearly so you can track progress in real time. ### Smart-contract protocol risk When you select a non-custodial lender, the loan is managed through that lender’s smart contracts. As with any on-chain system: * smart contracts may contain bugs or unintended behavior * protocol governance and design choices can influence risk * market conditions may affect liquidity and repayment These risks apply to all smart-contract systems. ### Borrow’s approach Borrow aims to simplify interactions with on-chain systems while maintaining transparency: * bridging and protocol steps are automated when needed * each step is shown in the interface * no actions occur without your approval Borrow does not remove protocol or network risk, but the platform makes these processes visible so you understand how your collateral is being handled. # Collateral Monitoring & Liquidation Borrow provides tools to help you understand the status of your loan, including your current Loan-to-Value (LTV), collateral value, and repayment requirements. These tools are intended to help you monitor risk while you remain in full control of your loan decisions. ### Loan visibility Your dashboard shows key information for each active loan, including: * current LTV * collateral value * outstanding loan balance * accrued interest (if applicable) This information helps you stay aware of how market movements or interest changes may affect your loan. ### Liquidation risk If the value of your BTC collateral falls relative to the borrowed amount, the loan may approach a liquidation threshold. Each lender defines its own parameters for: * liquidation LTV * interest model * required collateral levels Borrow displays these thresholds so you can understand the conditions under which liquidation may occur. ### User actions to manage loan health You can take steps at any time to adjust your loan and manage risk, including: * adding more BTC as collateral * repaying part or all of the borrowed amount These actions can help reduce your LTV and lower the risk of liquidation during periods of price volatility. ### Notifications & awareness Borrow highlights important loan status details in the interface, but users are responsible for monitoring their own positions, including: * market changes * collateral fluctuations * lender-defined terms Loan health may change quickly during periods of market volatility. ### Borrow’s role Borrow provides visibility into your loan and facilitates actions you choose to take. Borrow does not: * intervene automatically * adjust collateral on your behalf * prevent liquidations initiated by the lender * alter lender-defined parameters Managing loan risk is ultimately the borrower’s responsibility. # How Interest Rates Work Interest rates determine the cost of borrowing and play a significant role in the overall health of your BTC-backed loan. Understanding how rates behave helps you make more informed borrowing decisions. ### Why interest rates exist When you borrow against BTC, you pay interest to the lender in exchange for access to liquidity. The rate you pay is determined by the lender’s model, market conditions, and the availability of liquidity. ### What affects interest rates Interest rates can move for several reasons, including: * Borrowing demand: higher demand may increase rates. * Available liquidity: more supply may lower rates. * Market conditions: volatility or rapid inflows/outflows can affect utilization. * Lender parameters: each lender defines its own rules for adjusting rates. Rates are not static; they evolve based on how the lending market is behaving. ### Variable (Floating) interest rates A variable (or floating) rate adjusts over time. Most crypto-secured lenders use variable models because they react to changing market conditions. #### Variable rates may: * decrease when demand is low * increase when liquidity is scarce or utilization is high * update frequently depending on lender mechanisms Variable rates offer lower costs during favorable conditions but can rise unexpectedly. ### Fixed interest rates Some lenders offer fixed rates for loans. A fixed rate remains the same for the duration of the loan and does not change with market conditions. #### Fixed rates may: * provide predictability and easier planning * be higher than floating rates during stable market periods ### Why rate movement matters Changing interest rates can affect: * Total interest paid over the life of the loan * Loan-to-Value (LTV) ratio, since interest accrues * Liquidation risk, especially during periods of high volatility Monitoring your loan and understanding how rates behave is important during active borrowing. ### How Borrow presents interest rates Borrow: * shows each lender’s current rate before you take out a loan * displays your active rate and loan metrics in the dashboard * makes rate behavior visible without managing rates on your behalf This gives you clarity while keeping control in your hands. # Choosing an Interest Rate Borrow helps you compare available loan options across supported lenders so you can select the interest rate model and terms that best fit your needs before taking out a loan. ### What Borrow displays during loan creation When configuring a loan, Borrow presents: * the current interest rate offered by each lender * whether the rate is variable or fixed (if available) * the required collateral for the chosen loan * resulting LTV * any fees included in the loan This allows you to evaluate cost, predictability, and risk across lenders. ### Choosing a variable (floating) rate A variable rate may suit you if: * you want the lowest possible rate today * you’re comfortable with rates that may move * you plan to monitor your loan and market conditions * you expect stable or declining borrowing demand #### Considerations * variable rates can rise during market volatility * increased interest costs may affect LTV * borrowers should track how rate movement affects loan health ### Choosing a fixed rate A fixed rate may suit you if: * you prefer predictable borrowing costs * you want to avoid fluctuations during volatility * you are risk-averse or planning a long-term loan #### Considerations * fixed rates may be higher than variable rates * availability depends entirely on the lender * fixed-rate BTC-backed loans are less common in crypto markets ### After your loan is created Once active: * your interest rate follows the model defined by the lender * variable rates may move up or down over time * Borrow displays your current rate and LTV in the dashboard ### Borrow’s role Borrow provides visibility and comparison tools when you open a loan. Rate management decisions remain with the borrower. # Getting Started Start building with Sats Terminal and unlock the full potential of Bitcoin DeFi today! **Sats Terminal** gets you the best deal on your Runes swaps every time, we are the first Bitcoin-native aggregation protocol, offering seamless access to aggregated swaps and liquidity across multiple Bitcoin DEXes and DeFi platforms. Review the docs below to get a better understanding of the product offerings and to understand what is the best integration for you. {% embed url="" %} Our **JavaScript SDK** is built for easy integration into any front-end or back-end environment, enabling you to create custom UX/UI or scripts for Bitcoin swaps. It handles all communication with our smart routing API, manages error handling, and provides smooth integration for Bitcoin-native DeFi. Our **REST API** offers full access to aggregated swap data and allows for deep, customized integrations, providing a single endpoint to manage all swap needs across supported Bitcoin DEXes and liquidity sources. If you have no time, you can use the **URL Embed** to embed directly to our swap interface, pre-configured with your token and ref code, making it easy to onboard users with minimal setup. The fully customizable **Sats Terminal Embed** can be implemented in minutes, giving your users instant access to aggregated Bitcoin swaps without leaving your platform. Implement in 5 minutes and enable Bitcoin runes trading for your users from anywhere. It’s a quick way to onboard users into the Bitcoin DeFi ecosystem, without them leaving your website. # Getting Started A complete guide to swapping, analyzing, and exploring Spark tokens on Sats Terminal. ## **Overview** Spark on Sats Terminal provides a powerful, all-in-one interface for discovering Spark tokens, swapping them with optimized routing, and exploring market insights.\ This guide walks you through all available features, tools, and analytics panels. {% embed url="" fullWidth="false" %} *** ### **1. Swap** The **Swap** interface allows you to instantly exchange BTC ↔ Spark tokens using optimized routing for the best execution.
#### **Key Features** {% stepper %} {% step %} **Swap Settings** Configure your preferences for maximum control and efficiency. * **Auto / Manual Routing**\ Choose between automated smart routing or manual selection. * **Slippage Control**\ Adjust maximum slippage (%) based on your risk tolerance. * **BTC Amount Shortcuts** * Manual input * 25% / 50% / Max buttons for convenience {% endstep %} {% step %} **Token Selection** * Choose any Spark token for swapping * Instantly switch between **Buy** (BTC → token) and **Sell** (token → BTC) {% endstep %} {% step %} **Wallet Connection** Supported wallets: * **Spark Wallet** * **Xverse** * **Create new Spark Wallet** directly in the UI {% endstep %} {% endstepper %} *** ### **2. Pro Mode** The **Pro** section is designed for advanced traders, analysts, and researchers.\ It provides deep insights into Spark token markets: charts, holders, transactions, and bubble maps.
*** #### **2.1 Price Chart** Fully interactive chart with multiple timeframes: * **1h**, **1d**, **1w**, **1m**
*** #### **2.2 Market Stats** Displayed directly under the chart: | Metric | Description | | -------------- | ------------------------------------- | | **Market Cap** | Token’s fully diluted value | | **24h Volume** | Trading volume over the last 24 hours | | **TVL** | Total value locked across liquidity | | **Price** | Current price denominated in BTC | | **24h Change** | Percentage change in price | *** #### **2.3 Transactions Panel** Table of all token-related transactions: * Time * Type (buy/sell/mint/burn) * User (wallet address) * Token amount * BTC amount * Transaction hash (clickable)
*** #### **2.4 Holders** List of all token holders: | Column | Description | | -------------- | ----------------------- | | **Address** | Spark address of holder | | **Balance** | Amount of tokens held | | **Percentage** | % share of supply |
*** #### **2.5 Bubble Map** A visual representation of token distribution and holder relationships. **Bubble Map Sections:** **Overview** * Total holders * Relationship visualization * Bubble size = holder balance **Node Interaction** Click any bubble to view: * Address * Balance * Share of supply * Connections You can click any node to open the address directly on **SparkScan**.
*** #### **2.6 About Section** Includes: * Token description * Links to SparkScan * Official token Twitter * Additional metadata
*** ### **3. Explore** The **Explore** page provides a broad overview of all Spark pools and assets, designed for discovery and analysis.
*** #### **3.1 Pools Overview (List View)** A sortable list of all pools, including liquidity, price changes, and trends. #### **Columns** | Column | Description | | -------------- | --------------------------------------- | | **Asset** | Token in the pool | | **Pair** | Spark-BTC pair or other supported pairs | | **Price** | Current token price | | **24h Change** | % price movement | | **TVL** | Liquidity locked in the pool | | **24h Volume** | Trading volume | | **Holders** | Number of holders | | **Pools** | Number of available liquidity pools | | **Trend** | Visual sparkline graph | *** ### **Summary** The Spark integration on Sats Terminal gives users: * Optimized swaps * Advanced analytics * Real-time market insights * Wallet connectivity * Full token discovery tools All in a single, powerful Bitcoin-native interface. # Swap This page explains how to perform swaps inside the Spark ecosystem using Sats Terminal. Swapping tokens on Spark through Sats Terminal is designed to feel natural even for users unfamiliar with Bitcoin-native trading. The interface focuses on simplicity: you select the token, specify the amount, adjust your preferences, and submit the transaction through your wallet. Behind this lightweight workflow is a routing engine that automatically seeks the best available price across Spark liquidity. {% embed url="" %} *** ### **Connecting Your Wallet** Everything begins with connecting your wallet, which activates the swap panel and unlocks your balances. Sats Terminal supports Spark Wallet, Xverse, and even lets you create a new Spark Wallet instantly within the interface. This flexibility means that both experienced users and newcomers can start swapping without additional setup.
Once connected, your BTC and token balances sync automatically, ensuring all swap calculations reflect real on-chain data. *** ### **Preparing Your Swap** The swap interface is built for clarity. You choose which token you want to buy or sell, and Sats Terminal displays the estimated output, route, and expected slippage. Percentage shortcuts for BTC (25%, 50%, Max) make it easy to commit a part of your balance without typing numbers manually. You can swap in either direction: * **BTC → Spark token** * **Spark token → BTC** A single button flips the direction, which is useful if you're rebalancing or exiting a position quickly. {% hint style="info" %} Auto Routing is enabled by default, giving you the most efficient path. Manual Routing is available for advanced users wanting full control over pools and liquidity paths. {% endhint %} *** ### **Slippage & Routing Settings** Small adjustments to slippage can be crucial when dealing with volatile tokens or low-liquidity pairs.\ You are free to set: * Default recommended slippage * Custom slippage (useful for rapid market movement) * Auto routing for best execution * Manual routing for strategic control This combination allows beginners to keep things simple, while giving traders room to personalize their strategy. *** ### **Executing the Swap** Once settings are configured, confirm the swap. Your wallet will open a signing request showing the transaction details. After you approve the transaction, Spark’s settlement layer finalizes your swap on Bitcoin. The interface will show a confirmation once the swap is fully executed. Swapping is intentionally streamlined - the goal is to reduce friction, while still providing enough transparency and control to satisfy experienced traders. # Pro Charts The Pro section is where Spark’s market data becomes fully transparent. The Pro dashboard transforms raw blockchain data into an elegant market analytics environment. Instead of overwhelming users with complex charts, it organizes information around the essentials: price action, liquidity, holders, and real-time transactions. Whether you are exploring a new Spark token or evaluating long-term growth, Pro mode gives you all the tools you need in a clean, readable layout. {% embed url="" %} *** ### **Price Charts & Timeframes** At the top of the interface is the main price chart. You can switch between 1-hour, 1-day, 1-week, and 1-month views. Each timeframe highlights different market behaviors, from short-term volatility to structural trends. Candlestick movements, price stabilization zones, and momentum shifts are immediately visible.
The chart updates in real time, pulling its data directly from Spark’s on-chain activity. *** ### **Market Overview Metrics** Under the chart, you’ll find a compact but informative block containing: * Market cap * 24h trading volume * Total value locked (TVL) * Current token price * 24h price change
This section helps you instantly determine the token’s liquidity health and market interest. Large swings, quiet periods, sudden jumps in activity - everything becomes easier to interpret when paired with recent volume and TVL information. *** ### **Real-Time Transaction Feed** Every transaction involving the token appears in a live feed. This includes buys, sells, transfers, and interactions from major participants. Each entry lists the amount, timestamp, wallet address, token quantity, BTC value, and a direct link to SparkScan. Watching this feed gives you a sense of which addresses are active, whether whales are accumulating or selling, and how liquidity behaves during peak activity. *** ### **Holder Distribution** The holders tab reveals how widely distributed the token is. Each entry includes an address, its balance, and share of supply. Highly decentralized tokens tend to have a healthier market structure, while concentrated holdings near the top may indicate whales or early investors. The combination of charts, metrics, feed, and holders gives you a complete picture of the token’s current standing - helping you make informed decisions without leaving the page. # Bubble Map This page explains how the Bubble Map visualizes token ownership and relationships between wallets. The Bubble Map provides a visual interpretation of how Spark token supply is distributed across wallets. Rather than relying solely on lists and numbers, it converts wallet data into a system of interconnected nodes that highlight both the size of holdings and the relationships among them. *** ### **Visual Structure** Each bubble represents a wallet, with its size proportional to the token balance it holds. Bigger bubbles mean larger holders, while smaller ones represent regular users. This makes it easy to recognize whales or clusters of early participants at a glance.
{% hint style="info" %} When bubbles are connected, it means that those wallets interacted with each other through transfers or other on-chain operations. This builds an intuitive view of the network around a token. {% endhint %} *** ### **Exploring the Network** Clicking a bubble opens detailed information: * Wallet address * Balance * Share of total supply * A list of connected wallets A single click can reveal entire clusters, helping identify linked wallets, multi-address whales, or distribution patterns. {% hint style="info" %} If you want a deeper view, each wallet can be opened on SparkScan through a direct link. {% endhint %} *** ### **Why It Matters** The Bubble Map adds transparency to the Spark ecosystem.\ It helps: * Understand decentralization * Identify whales * Detect suspicious patterns * Track how supply changes over time Instead of reading one-dimensional data, the Bubble Map provides a living picture of the token’s ecosystem. # Explore Section The Explore section is designed to help users discover Spark tokens, review their performance, and compare liquidity across the entire ecosystem - all from a single page. Explore acts as the main directory for Spark assets. Instead of navigating through individual tokens one by one, you can see the full market landscape in a single, structured view. For traders, this page is often the starting point when searching for opportunities or tracking activity. {% embed url="" %} *** ### **Understanding the Pools List** Each row in the Explore table presents a compact summary of a Spark token or liquidity pool, including: * Token name and pair * Current price and its 24h change * TVL indicating available liquidity * 24h volume showing trading activity * Number of holders * A visual trend indicator representing recent price direction
This layout makes it easy to identify which assets are gaining traction and which are cooling off. *** ### **Filtering & Sorting** You can sort the table by any metric - price movement, liquidity, volume, or number of holders. This allows you to quickly surface the most relevant tokens based on your goal: discovering new assets, identifying stable pools, or monitoring high-activity zones. *** ### **Fast Navigation to Pro View** Clicking any row opens the token’s Pro view, letting you instantly dive deeper into charts, transactions, and holder structure. This smooth navigation makes it easy to shift from discovery to analysis without losing context. *** ### **Why Explore Is Useful** The Explore section brings transparency to Spark’s entire ecosystem. It lets you understand which tokens dominate liquidity, which are becoming more active, and how the ecosystem is evolving over time. For both newcomers and experienced traders, it’s the most efficient way to get a clear overview of the market. # Welcome Page Sats Terminal Swap SDK The **Sats Terminal Swap SDK** is a lightweight JavaScript package designed to simplify integration with our API. It acts as a wrapper, making it easier for developers to implement Bitcoin swap functionality directly into their applications without dealing with low-level API calls. With the Swap SDK, you can: * **Access Aggregated Liquidity**: Execute swaps with optimal rates across multiple Bitcoin DEXes. * **Simplify Integration**: Quickly add Bitcoin DeFi functionality to your project without writing complex routing logic. * **Handle Transactions Efficiently**: The SDK manages all communication with our API, ensuring smooth error handling and seamless performance. This SDK is built to save you time and effort, allowing you to focus on creating a better user experience while leveraging the full power of Bitcoin DeFi. Whether you’re building a wallet, a trading platform, or any Bitcoin-focused dApp, the Swap SDK is your gateway to seamless functionality. Get started today and unlock all Bitcoin Marketplaces in just a few lines of code. Check out our documentation for step-by-step integration instructions, code examples, and support resources. {% hint style="info" %} Contact our [business partnerships team](https://t.me/shavryliuk) to discover how you can partner with us and integrate [Sats Terminal](https://beta.satsterminal.com/) into your platform. {% endhint %} # Quick Start Integrate our Sats Terminal SDK to your dApp/Wallet/Swap UI Sats Terminal SDK package provides access to the Sats Terminal API to find and execute the best on-chain trade for runes across various exchanges. ### Installation {% tabs %} {% tab title="npm" %} ``` npm install satsterminal-sdk ``` {% endtab %} {% endtabs %} ### Importing the SDK The `satsterminal-sdk` is compatible with both CommonJS and ES6 module systems. **For CommonJS:** ``` const { SatsTerminal } = require('satsterminal-sdk'); ``` **For ES6 Modules/TypeScript:** ``` import { SatsTerminal } from 'satsterminal-sdk'; ``` {% hint style="info" %} The `satsterminal-sdk` library is natively type-safe, providing enhanced code reliability and developer experience, especially when using TypeScript. {% endhint %} ### Configuration The `satsterminal-sdk` requires configuration when initializing: ``` import { SatsTerminal } from 'satsterminal-sdk'; const satsTerminal = new SatsTerminal({ apiKey: 'your_api_key_here' }); ``` {% hint style="danger" %} API key is required and is rate-limited, you can find more details about this [here](https://satsterminal.gitbook.io/sats-terminal/getting-started/rate-limits-and-api-keys). {% endhint %} {% hint style="info" %} Apply for an API key here: [Sats Terminal Partnership Form](https://docs.google.com/forms/d/e/1FAIpQLSeTH9w1hVZQRLpu0gPjTM67gauuU2G95sy6vWpI9EJkb6Iz4g/viewform?usp=send_form) {% endhint %} # API Reference ### Methods #### swapQuote *** Get a quote for swapping tokens with simplified parameters. ```javascript async swapQuote(params: SwapV2QuoteParams): Promise ``` **Parameters:** * `amount` (string): Amount to swap (e.g., "0.00008") * `fromToken` (string): Source token (e.g., "BTC") * `toToken` (string): Destination token (e.g., "GOLD DUST") * `address` (string): User's Bitcoin address * `params` (Record\): Additional parameters * `protocol` (string): Protocol to use (e.g., "alkanes", "runes") * `marketplaces` (list): Marketplaces to include (e.g. \["MagicEden", "Dotswap]) **Example:** ```javascript const quote = await satsTerminal.swapQuote({ amount: "0.00008", fromToken: "BTC", toToken: "GOLD DUST", address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", params: {}, protocol: "alkanes" }); ``` **Example Response:** ```javascript { bestMarketplace: "IdClub", swapId: "st-mdyr4s5y-14277fae41249423", fromTokenAmount: "0.00007946", toTokenAmount: "1843.84645", metrics: { idclub: { percentFulfilled: "99.33", totalPurchased: "1843.84645000", percentDifference: "0.00", averageUnitPrice: "0.00000004" }, unisat: { percentFulfilled: "94.27", totalPurchased: "1257.00300000", percentDifference: "-31.83", averageUnitPrice: "0.00000006" } }, marketplaces: { Unisat: { fromTokenAmount: "0.00007542", toTokenAmount: "1257.003", swapId: "st-mdyr4rd9-653eb38defef8af2" }, IdClub: { fromTokenAmount: "0.00007946", toTokenAmount: "1843.84645", swapId: "st-mdyr4s5y-14277fae41249423" } } } ``` #### swapPSBT *** Get PSBT (Partially Signed Bitcoin Transaction) for the swap. ```javascript async swapPSBT(params: SwapV2PSBTParams): Promise ``` **Parameters:** * `marketplace` (string): Marketplace to use (e.g., "Unisat", "IdClub") * `swapId` (string): Swap ID from quote response * `address` (string): User's Bitcoin address * `publicKey` (string): User's public key * `paymentAddress` (string): Payment address * `paymentPublicKey` (string): Payment public key * `feeRate` (number): Fee rate (e.g., 3) * `slippage` (number): Slippage tolerance (e.g., 9) * `themeID?` (string | null): Theme ID (optional) * `protocol` (string): Protocol to use **Example:** ```javascript const psbt = await satsTerminal.swapPSBT({ marketplace: "Unisat", swapId: "st-mdyr4rd9-653eb38defef8af2", address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", feeRate: 3, slippage: 9, themeID: null, protocol: "alkanes" }); ``` **Example Response:** ```javascript { psbts: [ { base64: "cHNidP8BAP0WAQIAAAACxmLniE724xFErO3qK9jgKBkkVwz5dlTLTvdIVNw5JgMBAAAAAP////9CpNjLkmww5ugi0C91HbKTs5Sp9Ts+/fiobxMdIavsKgAAAAAA/////wVKAQAAAAAAACJRIPlmr/3KwxxsRAYxpoi+7UIK9UWARgEX5wKBAtW2LVMySgEAAAAAAAAiUSDhuqw5iXV8zvWrr9JnI/UX5lyEC0wBEnsf8wdHMT0gtQAAAAAAAAAAEGpdDQCp5zSmH7Oooon6AQGIEwAAAAAAACJRIMAdzzCKtujgeRdBvtozpwBAapRiHrmh7iK8lfPqe8HgTNQAAAAAAAAXqRTwcmaf/igf0hSlNZd3ss2y7lyJpYcAAAAAAAEA9gIAAAAAAQHjnkbASwGvRKDU+UFwaZ3QH5empgLm8vOYZ3wAFuOvzQEAAAAXFgAUY9wnP/vXXCJ9d3tDwzvzOL1cNV/9////AhAnAAAAAAAAFgAUksgOV4AYZsglBVge4QoNRmOaUK4t7QAAAAAAABepFPByZp/+KB/SFKU1l3eyzbLuXImlhwJHMEQCIBD6SFKCQKyb1Qv5hx6bHE8n6jpuzMWioSsoLtje7PtuAiA5WWCEEabkHchSVY7I6AachBHXIvDlCEVYaZjM8oRwXAEhAq9tcSQzhuOiSiPr9H6pHc8NEUuOwpFj7ZcW6bFKj+PYAAAAAAEDBAEAAAABBBYAFGPcJz/711wifXd7Q8M78zi9XDVfAAEBK0oBAAAAAAAAIlEg+Wav/crDHGxEBjGmiL7tQgr1RYBGARfnAoEC1bYtUzIBAwQBAAAAAAAAAAAA", hex: "70736274ff0100fd16010200000002c662e7884ef6e31144acedea2bd8e0281924570cf97654cb4ef74854dc3926030100000000ffffffff42a4d8cb926c30e6e822d02f751db293b394a9f53b3efdf8a86f131d21abec2a0000000000ffffffff054a01000000000000225120f966affdcac31c6c440631a688beed420af54580460117e7028102d5b62d53324a01000000000000225120e1baac3989757ccef5abafd26723f517e65c840b4c01127b1ff30747313d20b50000000000000000106a5d0d00a9e734a61fb3a8a289fa01018813000000000000225120c01dcf308ab6e8e0791741beda33a700406a94621eb9a1ee22bc95f3ea7bc1e04cd400000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a58700000000000100f602000000000101e39e46c04b01af44a0d4f94170699dd01f97a6a602e6f2f398677c0016e3afcd010000001716001463dc273ffbd75c227d777b43c33bf338bd5c355ffdffffff02102700000000000016001492c80e57801866c82505581ee10a0d46639a50ae2ded00000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a58702473044022010fa48528240ac9bd50bf9871e9b1c4f27ea3a6eccc5a2a12b282ed8deecfb6e02203959608411a6e41dc852558ec8e8069c8411d722f0e50845586998ccf284705c012102af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d80000000001030401000000010416001463dc273ffbd75c227d777b43c33bf338bd5c355f0001012b4a01000000000000225120f966affdcac31c6c440631a688beed420af54580460117e7028102d5b62d533201030401000000000000000000", inputs: [0] } ], swapId: "st-mdyrtdw5-cfbcc46b313f348a" } ``` #### swapSubmit Submit signed PSBT to complete the swap. ```javascript async swapSubmit(params: SwapV2SubmitParams): Promise ``` **Parameters:** * `marketplace` (string): Marketplace to use * `swapId` (string): Swap ID from PSBT response * `address` (string): User's Bitcoin address * `publicKey` (string): User's public key * `paymentAddress` (string): Payment address * `paymentPublicKey` (string): Payment public key * `protocol` (string): Protocol to use * `signedPsbts` (string\[]): Array of signed PSBT hex strings **Example:** ```javascript const result = await satsTerminal.swapSubmit({ marketplace: "Seekermint", swapId: "st-mdonupt8-897950607c0ef3d2", address: "bc1puxa2cwvfw47vaadt4lfxwgl4zln9epqtfsq3y7cl7vr5wvfayz6s22mmwp", publicKey: "dd4c950d7a5f86e92235687cffeee1bfb61b5c8a9e15b80751077c3d4315821c", paymentAddress: "3PcP9J6C9ZNQpTRHrtqFBhP3LoBjSmMkZq", paymentPublicKey: "02af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d8", protocol: "runes", signedPsbts: ["70736274ff0100fd030102000000021673b1a059f118d75c27a4c11ef366c137d7a0b77e141d6202b6abb348d84e120400000000ffffffff9e4d7db2d381db866caed76a53b0318a747fd3e83f7d3e8f796efcffab69bad50100000000ffffffff050000000000000000156a5d1200c0a2330388ffc358010000f0ec959636022202000000000000225120e1baac3989757ccef5abafd26723f517e65c840b4c01127b1ff30747313d20b522020000000000001600142d0e4a3334c4ba29e9304831343ef6e6b9927a5b88130000000000001600142d0e4a3334c4ba29e9304831343ef6e6b9927a5bb6ff01000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a5870000000000010120981902000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a587220202af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d84730440220257cd5c3dc7a1d66d76ac8b23479cdd9a1cacfd48f6e29b8e4a48b84c75df182022047885e889da1f0685796269c2694ec8d541a315fdc46258b22e7d9e04ae347190101030401000000010416001463dc273ffbd75c227d777b43c33bf338bd5c355f0001011f22020000000000001600142d0e4a3334c4ba29e9304831343ef6e6b9927a5b01030401000000000000000000"] }); ``` **Example Response:** ```javascript { marketplace: "Seekermint", txid: "abc123def456789...", rbfProtection: { fundsPreparationTxId: "prep_tx_123", fulfillmentId: "fulfill_456" }, isRbfTxid: false, error: undefined } ``` #### **signIn** *** Register and authenticate a user with their Bitcoin and Ordinals addresses. ```javascript async signIn(params: SignInParams): Promise ``` **Parameters:** * `ord_address` (string): Ordinals address * `btc_address` (string): Bitcoin address * `ord_public_key` (string): Ordinals public key * `btc_public_key` (string): Bitcoin public key * `provider` (string): Wallet provider (e.g., 'xverse', 'unisat') **Example:** ```javascript const signIn = await satsTerminal.signIn({ ord_address: "bc1...", btc_address: "3Pc...", ord_public_key: "...", btc_public_key: "...", provider: "xverse" }); ``` #### bind *** Bind a user's wallet to Unisat and DotSwap. This is required only once before performing transactions. ```javascript async bind(params: BindParams): Promise ``` **Parameters:** * `btcAddress` (string): Bitcoin address * `nftAddress` (string): Ordinals address * `sign` (string): User's signature of the bind message **Example:** ```javascript const bind = await satsTerminal.bind({ btcAddress: "3Pc...", nftAddress: "bc1...", sign: "user_signature_here" }); ``` #### **points** *** Get the user's accumulated Amber points balance. ```javascript async points(params: PointsParams): Promise ``` **Parameters:** * `ord_address` (string): Ordinals address **Example:** ```javascript const points = await satsTerminal.points({ ord_address: "bc1..." }); ``` #### **search** *** Search for runes by name. ```javascript async search(params: SearchParams): Promise ``` **Parameters:** * `rune_name` (string): The name of the rune to search for * `sell` (boolean, optional): Whether to search for sell orders **Example:** ```javascript const result = await satsTerminal.search({ rune_name: 'LOBO•THE•WOLF•PUP', sell: false }); ``` #### **popularCollections** *** Fetch popular rune collections. ```javascript async popularCollections(params: PopularCollectionsParams): Promise ``` **Example:** ```javascript const collections = await satsTerminal.popularCollections(); ``` # Migration Guide {% hint style="success" %} The SatsTerminal SDK V2 API introduces a significantly simplified approach to token swapping while maintaining full backward compatibility with V1. This guide will help you understand the conceptual differences and provide practical examples for migrating your code. {% endhint %} ### Key Benefits of V2 {% stepper %} {% step %} **Simplified Direction Control** Clear `fromToken`/`toToken` parameters instead of confusing `sell` boolean {% endstep %} {% step %} **Automatic Order Management** No need to manually handle orders - everything managed via `swapId` {% endstep %} {% step %} **Multiple PSBT Support** Can handle complex transactions requiring multiple PSBTs {% endstep %} {% step %} **Normalized Data** Consistent, clean response structures {% endstep %} {% step %} **Better UX** Automatic marketplace selection and optimization {% endstep %} {% step %} **Reduced Complexity** Fewer parameters and simpler responses {% endstep %} {% endstepper %} #### Conceptual Differences **1. Direction Control** **V1 Problem**: The `sell` boolean parameter was confusing and error-prone. ```javascript // V1: Confusing direction control const quote = await client.fetchQuote({ btcAmount: "0.00008", runeName: "GOLD•DUST", sell: false, // What does this mean? Buy runes with BTC? Sell BTC for runes? address: "bc1..." }); ``` **V2 Solution**: Clear, intuitive `fromToken` and `toToken` parameters. ```javascript // V2: Crystal clear direction const quote = await client.swapQuote({ amount: "0.00008", fromToken: "BTC", // I'm swapping FROM BTC toToken: "GOLD DUST", // I'm swapping TO GOLD DUST address: "bc1...", protocol: "alkanes", params: {} }); ``` **2. Order Management** **V1 Problem**: Manual order selection and management across multiple API calls. ```javascript // V1: Manual order management const quote = await client.fetchQuote({ ... }); const selectedOrders = quote.selectedOrders; const psbt = await client.getPSBT({ orders: selectedOrders, // Must pass orders explicitly ... }); const result = await client.confirmPSBT({ orders: selectedOrders, // Must pass orders again ... }); ``` **V2 Solution**: Automatic order management via `swapId`. ```javascript // V2: Automatic order management const quote = await client.swapQuote({ ... }); // Orders are automatically managed internally const psbt = await client.swapPSBT({ swapId: quote.swapId, // No orders needed - all handled automatically ... }); const result = await client.swapSubmit({ swapId: psbt.swapId, // Still no orders needed ... }); ``` **3. PSBT Handling** **V1 Limitation**: Always returned a single PSBT. ```javascript // V1: Single PSBT only interface PSBTResponse { psbtBase64: string; // Single PSBT psbtHex: string; // Single PSBT inputs: number[]; } ``` **V2 Enhancement**: Can return multiple PSBTs for complex transactions. ```javascript // V2: Multiple PSBTs supported interface SwapV2PSBTResponse { psbts: SwapV2PSBT[]; // Array of PSBTs swapId: string; } interface SwapV2PSBT { base64: string; hex: string; inputs: number[]; } ``` **4. Data Structure Consistency** **V1 Problem**: Inconsistent, nested data structures. ```javascript // V1: Complex, inconsistent structure { selectedOrders: [ { market: "Unisat", // Sometimes "market" marketplace: "MagicEden", // Sometimes "marketplace" price: 0.00000004, // Number format formattedUnitPrice: "0.490352", // String format // ... many other inconsistent fields } ], totalFormattedAmount: "0.00007542", totalPrice: "1843.84645", metrics: { /* complex nested structure */ } } ``` **V2 Solution**: Normalized, consistent data format. ```javascript // V2: Clean, consistent structure { bestMarketplace: "IdClub", swapId: "st-mdyr4s5y-14277fae41249423", fromTokenAmount: "0.00007946", // Consistent string format toTokenAmount: "1843.84645", // Consistent string format metrics: { idclub: { percentFulfilled: "99.33", totalPurchased: "1843.84645000", percentDifference: "0.00", averageUnitPrice: "0.00000004" } }, marketplaces: { IdClub: { fromTokenAmount: "0.00007946", toTokenAmount: "1843.84645", swapId: "st-mdyr4s5y-14277fae41249423" } } } ``` #### Migration Examples **Example 1: Basic Rune Purchase** **V1 Implementation:** ```javascript // V1: Complex rune purchase flow async function buyRunesV1() { const client = new SatsTerminal({ apiKey: 'your-api-key' }); try { // Step 1: Get quote const quote = await client.fetchQuote({ btcAmount: 0.0001, runeName: "LOBO•THE•WOLF•PUP", address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", sell: false, // Buying runes with BTC marketplaces: ["MagicEden"] }); // Step 2: Generate PSBT with manual order management const psbtResponse = await client.getPSBT({ orders: quote.selectedOrders, // Manual order selection address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", runeName: "LOBO•THE•WOLF•PUP", feeRate: 5, slippage: 9 }); // Step 3: Sign PSBT (user implementation) const signedPsbtBase64 = await signPSBT(psbtResponse.rbfProtected.base64); const signedRbfPsbtBase64 = await signPSBT(psbtResponse.rbfProtected.base64); // Step 4: Confirm with manual order management again const confirmation = await client.confirmPSBT({ orders: quote.selectedOrders, // Must pass orders again address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", signedPsbtBase64: signedPsbtBase64, signedRbfPsbtBase64: signedRbfPsbtBase64, swapId: psbtResponse.swapId, runeName: "LOBO•THE•WOLF•PUP" }); console.log('V1 Transaction completed:', confirmation.txid); return confirmation; } catch (error) { console.error('V1 Error:', error); throw error; } } ``` **V2 Implementation (Migrated):** ```javascript // V2: Simplified rune purchase flow async function buyRunesV2() { const client = new SatsTerminal({ apiKey: 'your-api-key' }); try { // Step 1: Get quote with clear direction const quote = await client.swapQuote({ amount: "0.0001", fromToken: "BTC", // Clear: swapping FROM BTC toToken: "LOBO•THE•WOLF•PUP", // Clear: swapping TO this rune address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", protocol: "runes", params: {}, marketplaces: ["MagicEden"] }); // Step 2: Generate PSBT - no manual order management needed const psbtResponse = await client.swapPSBT({ marketplace: quote.bestMarketplace, // Use best marketplace from quote swapId: quote.swapId, // Automatic order management address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", protocol: "runes", feeRate: 5, slippage: 9 }); // Step 3: Sign all PSBTs (V2 can have multiple) const signedPsbts = await Promise.all( psbtResponse.psbts.map(psbt => signPSBT(psbt.hex)) ); // Step 4: Submit - no order management needed const result = await client.swapSubmit({ marketplace: quote.bestMarketplace, swapId: psbtResponse.swapId, // Automatic order management address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", protocol: "runes", signedPsbts: signedPsbts }); console.log('V2 Transaction completed:', result.txid); return result; } catch (error) { console.error('V2 Error:', error); throw error; } } ``` **Example 2: Selling Runes for BTC** **V1 Implementation:** ```javascript // V1: Selling runes (confusing direction) async function sellRunesV1() { const client = new SatsTerminal({ apiKey: 'your-api-key' }); const quote = await client.fetchQuote({ btcAmount: "20000", // Amount of runes to sell (confusing parameter name) runeName: "GOLD DUST", // Confusing parameter name address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", sell: true, // This means we're selling runes for BTC marketplaces: ["Unisat"], protocol: 'alkanes' }); const psbt = await client.getPSBT({ orders: quote.selectedOrders, address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", runeName: "GOLD DUST", sell: true, // Must remember to set this again feeRate: 3 protocol: 'alkanes' }); const signedPsbt = await signPSBT(psbt.psbtHex); const result = await client.confirmPSBT({ orders: quote.selectedOrders, address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", signedPsbtBase64: signedPsbt, swapId: psbt.swapId, runeName: "GOLD DUST", sell: true // Must remember this in every call protocol: 'alkanes' }); return result; } ``` **V2 Implementation (Migrated):** ```javascript // V2: Selling runes (crystal clear direction) async function sellRunesV2() { const client = new SatsTerminal({ apiKey: 'your-api-key' }); const quote = await client.swapQuote({ amount: "20000", fromToken: "GOLD DUST", // Clear: swapping FROM GOLD DUST (protocol agnostic) toToken: "BTC", // Clear: swapping TO BTC address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", protocol: "alkanes", params: {} }); const psbt = await client.swapPSBT({ marketplace: quote.bestMarketplace, swapId: quote.swapId, // No need to track orders address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", protocol: "alkanes", feeRate: 3, slippage: 5 }); const signedPsbts = await Promise.all( psbt.psbts.map(p => signPSBT(p.hex)) ); const result = await client.swapSubmit({ marketplace: quote.bestMarketplace, swapId: psbt.swapId, // No need to track orders address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj", publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc", paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559vzk4epc", paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588", protocol: "alkanes", signedPsbts: signedPsbts }); return result; } ``` #### Migration Checklist {% stepper %} {% step %} **Update Method Names** * Replace `fetchQuote()` with `swapQuote()` * Replace `getPSBT()` with `swapPSBT()` * Replace `confirmPSBT()` with `swapSubmit()` {% endstep %} {% step %} **Update Parameters** * Replace `sell: boolean` with `fromToken` and `toToken` strings * Replace `btcAmount` with `amount` (works for any token) * Replace `runeName` with appropriate `fromToken` or `toToken` * Add `protocol` parameter ("runes" or "alkanes") {% endstep %} {% step %} **Update Response Handling** * Replace `quote.selectedOrders` usage with `quote.swapId` * Update PSBT handling to support multiple PSBTs: `psbt.psbts[]` * Remove manual order management code * Update data access patterns for normalized structure {% endstep %} {% step %} **Update PSBT Signing** * Change from single PSBT to array of PSBTs * Update signing loop: `psbt.psbts.map(p => signPSBT(p.hex))` or use built-in wallet signPsbts method. * Change parameter from `signedPsbtBase64` to `signedPsbts[]` {% endstep %} {% step %} **Simplify Error Handling** * Remove order-related error handling * Simplify state management error handling * Focus on swap-specific errors (slippage, balance, etc.) {% endstep %} {% endstepper %} #### Common Pitfalls and Solutions **Pitfall 1: Single PSBT Assumption** **Problem**: Assuming V2 returns only one PSBT like V1. **Solution**: ```javascript // V1: Single PSBT const signedPsbt = await signPSBT(psbt.psbtHex); // V2: Multiple PSBTs const signedPsbts = await Promise.all( psbt.psbts.map(p => signPSBT(p.hex)) // or signPSBTs for some wallets ); ``` **Pitfall 2: Order Management Confusion** **Problem**: Trying to manage orders manually in V2. **Solution**: ```javascript // V1: Manual order management const psbt = await client.getPSBT({ orders: quote.selectedOrders, // Don't do this in V2 // ... }); // V2: Automatic order management const psbt = await client.swapPSBT({ swapId: quote.swapId, // Use swapId instead // ... }); ``` **Pitfall 3: Direction Confusion** **Problem**: Converting `sell` boolean incorrectly. **Solution**: ```javascript // V1: Confusing sell parameter const quote = await client.fetchQuote({ btcAmount: "0.0001", runeName: "GOLD DUST", sell: false // Buying runes with BTC }); // V2: Clear direction - CORRECT conversion const quote = await client.swapQuote({ amount: "0.0001", fromToken: "BTC", // What we're spending toToken: "GOLD DUST", // What we're getting // ... }); // WRONG conversion would be: // fromToken: "GOLD DUST", toToken: "BTC" (this would be selling) ``` # Examples End-to-end example scripts for easy implementation using the SDK V2. #### Example 1: Complete Rune Purchase Flow Below is a complete example flow for buying runes using the simplified SDK V2, including waiting for user input for signed PSBTs: ```javascript import { SatsTerminal } from 'satsterminal-sdk'; import readlineSync from 'readline-sync'; // Configuration const CONFIG = { apiKey: 'your_api_key_here', }; // Trade Parameters const TRADE_PARAMS = { fromToken: 'BTC', toToken: 'LOBO•THE•WOLF•PUP', address: 'bc1p...', publicKey: '...', paymentAddress: '3Pc...', paymentPublicKey: '...', amount: '0.0001', protocol: 'runes' }; // Initialize the SDK const satsTerminal = new SatsTerminal(CONFIG); // Function to get user input for signed PSBTs (V2 can have multiple) const getSignedPSBTs = (psbts) => { console.log(`\nPlease sign ${psbts.length} PSBT(s):`); const signedPsbts = []; for (let i = 0; i < psbts.length; i++) { console.log(`\nPSBT ${i + 1} hex: ${psbts[i].hex}`); const signed = readlineSync.question(`Enter signed PSBT ${i + 1} hex: `); signedPsbts.push(signed); } return signedPsbts; }; // Main execution (async () => { try { // 1. Get a quote for the swap console.log('\n1. Fetching swap quote...'); const quote = await satsTerminal.swapQuote({ amount: TRADE_PARAMS.amount, fromToken: TRADE_PARAMS.fromToken, toToken: TRADE_PARAMS.toToken, address: TRADE_PARAMS.address, protocol: TRADE_PARAMS.protocol, params: {} }); console.log('Best marketplace:', quote.bestMarketplace); console.log('Swap ID:', quote.swapId); console.log('From token amount:', quote.fromTokenAmount); console.log('To token amount:', quote.toTokenAmount); console.log('Available marketplaces:', Object.keys(quote.marketplaces)); // 2. Create PSBT(s) for the swap console.log('\n2. Creating PSBT(s)...'); const psbtResponse = await satsTerminal.swapPSBT({ marketplace: quote.bestMarketplace, swapId: quote.swapId, address: TRADE_PARAMS.address, publicKey: TRADE_PARAMS.publicKey, paymentAddress: TRADE_PARAMS.paymentAddress, paymentPublicKey: TRADE_PARAMS.paymentPublicKey, protocol: TRADE_PARAMS.protocol, feeRate: 5, slippage: 9, themeID: null }); console.log(`Created ${psbtResponse.psbts.length} PSBT(s)`); console.log('Updated swap ID:', psbtResponse.swapId); // Wait for user to sign all PSBTs const signedPsbts = getSignedPSBTs(psbtResponse.psbts); // 3. Submit the signed PSBTs console.log('\n3. Submitting signed PSBTs...'); const result = await satsTerminal.swapSubmit({ marketplace: quote.bestMarketplace, swapId: psbtResponse.swapId, address: TRADE_PARAMS.address, publicKey: TRADE_PARAMS.publicKey, paymentAddress: TRADE_PARAMS.paymentAddress, paymentPublicKey: TRADE_PARAMS.paymentPublicKey, protocol: TRADE_PARAMS.protocol, signedPsbts: signedPsbts }); console.log('✅ Swap completed successfully!'); console.log('Transaction ID:', result.txid); console.log('Marketplace used:', result.marketplace); } catch (error) { console.error('Error:', error.message); } })(); ``` #### Example 2: Selling Runes for BTC ```javascript // Import the SDK import { SatsTerminal } from 'satsterminal-sdk'; import readlineSync from 'readline-sync'; // Configuration const CONFIG = { // Your API key for SatsTerminal apiKey: 'your_api_key_here', }; // Trade Parameters const TRADE_PARAMS = { // Clear direction: selling runes for BTC fromToken: 'DOG•GO•TO•THE•MOON', // What we're selling toToken: 'BTC', // What we want to receive address: 'bc1puxa2cwvfw47vaadt4lfxwgl4zln9epqtfsq3y7cl7vr5wvfayz6s22mmwp', publicKey: 'dd4c950d7a5f86e92235687cffeee1bfb61b5c8a9e15b80751077c3d4315821c', paymentAddress: '3PcP9J6C9ZNQpTRHrtqFBhP3LoBjSmMkZq', paymentPublicKey: '02af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d8', sellAmount: "10000", // Amount of runes to sell protocol: 'runes' }; // Initialize the SDK const satsTerminal = new SatsTerminal(CONFIG); // Function to get user input for signed PSBTs const getSignedPSBTs = (psbts) => { console.log(`\nFound ${psbts.length} PSBT(s) to sign:`); const signedPsbts = []; for (let i = 0; i < psbts.length; i++) { console.log(`\nPSBT ${i + 1}:`); console.log(`Base64: ${psbts[i].base64.substring(0, 50)}...`); console.log(`Hex: ${psbts[i].hex.substring(0, 50)}...`); console.log(`Inputs: [${psbts[i].inputs.join(', ')}]`); const signed = readlineSync.question(`Enter signed PSBT ${i + 1} hex: `); signedPsbts.push(signed); } return signedPsbts; }; // Main execution block (sell runes for BTC) (async () => { try { // 1. Get a quote for selling runes console.log('\n1. Fetching sell quote...'); console.log('Trade parameters:', TRADE_PARAMS); const quote = await satsTerminal.swapQuote({ amount: TRADE_PARAMS.sellAmount, fromToken: TRADE_PARAMS.fromToken, // Selling runes toToken: TRADE_PARAMS.toToken, // For BTC address: TRADE_PARAMS.address, protocol: TRADE_PARAMS.protocol, params: {} }); console.log('✅ Quote received:'); console.log('Best marketplace:', quote.bestMarketplace); console.log('Swap ID:', quote.swapId); console.log('Selling:', quote.fromTokenAmount, TRADE_PARAMS.fromToken); console.log('Receiving:', quote.toTokenAmount, 'BTC'); // Show all available marketplaces console.log('\nAvailable marketplaces:'); Object.entries(quote.marketplaces).forEach(([name, data]) => { console.log(`- ${name}: ${data.fromTokenAmount} → ${data.toTokenAmount} BTC`); }); // 2. Create PSBT(s) for the swap console.log('\n2. Creating PSBT(s)...'); const psbtResponse = await satsTerminal.swapPSBT({ marketplace: quote.bestMarketplace, swapId: quote.swapId, address: TRADE_PARAMS.address, publicKey: TRADE_PARAMS.publicKey, paymentAddress: TRADE_PARAMS.paymentAddress, paymentPublicKey: TRADE_PARAMS.paymentPublicKey, protocol: TRADE_PARAMS.protocol, feeRate: 5, slippage: 9, themeID: null }); console.log(`✅ Created ${psbtResponse.psbts.length} PSBT(s)`); console.log('Updated swap ID:', psbtResponse.swapId); // Wait for user to sign all PSBTs const signedPsbts = getSignedPSBTs(psbtResponse.psbts); // 3. Submit the signed PSBTs console.log('\n3. Submitting signed PSBTs...'); const confirmation = await satsTerminal.swapSubmit({ marketplace: quote.bestMarketplace, swapId: psbtResponse.swapId, address: TRADE_PARAMS.address, publicKey: TRADE_PARAMS.publicKey, paymentAddress: TRADE_PARAMS.paymentAddress, paymentPublicKey: TRADE_PARAMS.paymentPublicKey, protocol: TRADE_PARAMS.protocol, signedPsbts: signedPsbts }); console.log('✅ Sell order completed successfully!'); console.log('Transaction ID:', confirmation.txid); console.log('Marketplace:', confirmation.marketplace); } catch (error) { console.error('Error:', error.message); } })(); ``` #### Example 3: Alkanes Swap ```javascript import { SatsTerminal } from 'satsterminal-sdk'; import readlineSync from 'readline-sync'; /** * This example demonstrates swapping BTC for alkanes tokens using V2 API */ // Configuration const CONFIG = { apiKey: 'your_api_key_here', }; // Trade Parameters for Alkanes const TRADE_PARAMS = { fromToken: 'BTC', toToken: 'GOLD DUST', // Alkanes token address: 'bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj', publicKey: '03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc', paymentAddress: 'bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc', paymentPublicKey: '02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588', amount: '0.00008', protocol: 'alkanes' // Different protocol }; const satsTerminal = new SatsTerminal(CONFIG); const getSignedPSBTs = (psbts) => { console.log(`\nPlease sign ${psbts.length} PSBT(s) for alkanes swap:`); const signedPsbts = []; psbts.forEach((psbt, index) => { console.log(`\nPSBT ${index + 1} details:`); console.log(`- Inputs: [${psbt.inputs.join(', ')}]`); console.log(`- Hex length: ${psbt.hex.length} characters`); const signed = readlineSync.question(`Enter signed PSBT ${index + 1} hex: `); signedPsbts.push(signed); }); return signedPsbts; }; (async () => { try { console.log('🔄 Starting alkanes token swap...'); // 1. Get quote for alkanes swap console.log('\n1. Getting alkanes swap quote...'); const quote = await satsTerminal.swapQuote({ amount: TRADE_PARAMS.amount, fromToken: TRADE_PARAMS.fromToken, toToken: TRADE_PARAMS.toToken, address: TRADE_PARAMS.address, protocol: TRADE_PARAMS.protocol, params: {} }); console.log('✅ Alkanes quote received:'); console.log(`Swapping ${quote.fromTokenAmount} BTC → ${quote.toTokenAmount} ${TRADE_PARAMS.toToken}`); console.log('Best marketplace:', quote.bestMarketplace); // Show metrics for different marketplaces if (quote.metrics) { console.log('\nMarketplace performance:'); Object.entries(quote.metrics).forEach(([marketplace, metrics]) => { console.log(`- ${marketplace}: ${metrics.percentFulfilled}% fulfilled, avg price: ${metrics.averageUnitPrice}`); }); } // 2. Create PSBTs console.log('\n2. Creating alkanes swap PSBTs...'); const psbtResponse = await satsTerminal.swapPSBT({ marketplace: quote.bestMarketplace, swapId: quote.swapId, address: TRADE_PARAMS.address, publicKey: TRADE_PARAMS.publicKey, paymentAddress: TRADE_PARAMS.paymentAddress, paymentPublicKey: TRADE_PARAMS.paymentPublicKey, protocol: TRADE_PARAMS.protocol, feeRate: 3, slippage: 5, themeID: null }); console.log(`✅ Generated ${psbtResponse.psbts.length} PSBT(s) for alkanes swap`); // Sign PSBTs const signedPsbts = getSignedPSBTs(psbtResponse.psbts); // 3. Submit alkanes swap console.log('\n3. Executing alkanes swap...'); const result = await satsTerminal.swapSubmit({ marketplace: quote.bestMarketplace, swapId: psbtResponse.swapId, address: TRADE_PARAMS.address, publicKey: TRADE_PARAMS.publicKey, paymentAddress: TRADE_PARAMS.paymentAddress, paymentPublicKey: TRADE_PARAMS.paymentPublicKey, protocol: TRADE_PARAMS.protocol, signedPsbts: signedPsbts }); console.log('🎉 Alkanes swap completed!'); console.log('Transaction ID:', result.txid); console.log(`Successfully swapped BTC for ${TRADE_PARAMS.toToken}`); } catch (error) { console.error('Error:', error.message); } })(); ``` # Common Issues #### Invalid API Key *** Ensure your API key is valid and properly configured. Only approved partners can use the SDK. {% hint style="info" %} Apply for an API key here: [Sats Terminal Partnership Form](https://docs.google.com/forms/d/e/1FAIpQLSeTH9w1hVZQRLpu0gPjTM67gauuU2G95sy6vWpI9EJkb6Iz4g/viewform?usp=send_form) {% endhint %} #### Network Errors *** * Check your internet connection * Verify the API endpoint is accessible * Check if your firewall is blocking requests #### PSBT Errors *** * Ensure all required parameters are provided * Ensure the PSBTs are valid and signed * Verify the format of public keys and addresses *** For additional support, contact our support team. # Getting Started Our widget program is a wonderful way for projects, whether it's a DeFi application or a memecoin, to enable trading on your webpage using a Sats Terminal widget that is customizable to your branding current UI. The entire process is simple with minimal effort required with our intuitive dashboard: {% hint style="info" %} **Dashboard Link:** [**https://satsterminal-admin.vercel.app/**](https://satsterminal-admin.vercel.app/) {% endhint %} To get an account, please contact us! # Creating a New Widget 1. Once you've logged into the Sats Terminal, click on the **Widget Playground** tab: ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252Fw4D0MbhzcUeJJbLwDI2g%252Fimage.png%3Falt%3Dmedia%26token%3D7c6fc8f2-4907-47c8-a4ee-0ace7abba01d\&width=768\&dpr=4\&quality=100\&sign=3fc4b5c\&sv=2) 2. In the upper-right corner, click on the **+CREATE NEW WIDGET** button: ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FNl8mcwdyV1COWJCxDDHj%252Fimage.png%3Falt%3Dmedia%26token%3D1368dc51-bb4f-42c4-aed8-19e421262185\&width=768\&dpr=4\&quality=100\&sign=8803026\&sv=2) # Basic Settings ### **Title** **Title** changes the title of the widget as it shows up in your **Widget Playground** dashboard. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FGdOTjVhgI4yu0QzzifbA%252FScreenshot%25202025-01-19%2520at%25205.30.59%2520PM.png%3Falt%3Dmedia%26token%3Df83f753b-fb05-4b0c-92ea-3a730078a40d\&width=768\&dpr=4\&quality=100\&sign=34b8a432\&sv=2) ### **Logo** **Logo** allows you to upload your brand logo that shows up in the bottom of your widget. This can be either a **jpg**, **png**, or **animated/still gif**. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FAZu8zwuvX6YJSj3IvYHa%252Flogo.jpg%3Falt%3Dmedia%26token%3D11bc2a03-5279-437e-b91f-6f5d9a7b0f18\&width=768\&dpr=4\&quality=100\&sign=d3941a35\&sv=2) ### **Background Image** **Background Image** allows you to upload a custom made background for your widget. Refer to the **Custom Background Design** section for a design template and more details on how to design for this. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FU0UnioBmOZZaFPQpUoTi%252Fbackground_image.jpg%3Falt%3Dmedia%26token%3D7df5dd93-66dc-4236-aa02-ea02efdca321\&width=768\&dpr=4\&quality=100\&sign=db06b778\&sv=2) ### **Default Runes** Setting a Def**ault Runes** allows your widget to only allow the user to buy that rune. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FyH3LnNS8aiVCvEugCnBM%252Fdefault_runes.jpg%3Falt%3Dmedia%26token%3Dc627ee26-28b0-4d0a-9b73-7c4536ae455d\&width=768\&dpr=4\&quality=100\&sign=8ef202e6\&sv=2) ### **Dark Mode** The **Dark Mode Switch** allows you to change the **Sats Terminal Logo** and **Wallet Selection Background** to either white or black. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252Fw27YSkjmIDC5eKIAfrm7%252Fdark_mode_01.jpg%3Falt%3Dmedia%26token%3D60a3b786-7e24-4565-93cf-93de4ff67d45\&width=768\&dpr=4\&quality=100\&sign=5ffffa40\&sv=2) Dark Mode affecting the Sats Terminal logo ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FtgGfmSvkCg4KsrDdX1wD%252Fdark_mode_02.jpg%3Falt%3Dmedia%26token%3Da0029b4e-5e82-41dc-bb1c-b07b977c954d\&width=768\&dpr=4\&quality=100\&sign=7cbea094\&sv=2) Dark Mode affecting the wallet connection background ### Custom Background Design Design your background in **800 x 1300 (pixels)** 1. **Download** our following template guide (png): Open 2. **Design the background** to your liking using the guides to see where the buttons are and where it won't be visible. Try to make the **design more simple at the bottom** or the design to leave room for the token image and the Sats Terminal logo, which will be either black or white at the bottom. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FOrjRcRIb6NTjSocDzbEV%252Fbackground-creation.gif%3Falt%3Dmedia%26token%3D7769f853-3f96-45a7-b19f-56d1a3eda3c6\&width=768\&dpr=4\&quality=100\&sign=576e5c3e\&sv=2) Designing with the png template 3. Make sure that the final image that you save for upload **does not show the panel guides**. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FInGtn4MQ849vUGBV1CTW%252Fbackground.jpg%3Falt%3Dmedia%26token%3Deb374ef6-b47a-41f7-80a8-bb0d711c76af\&width=768\&dpr=4\&quality=100\&sign=544f8d71\&sv=2) Custom BG ready for upload # Colors ### **Overiew** You can customize colors by using the **Color Selection Panel**, **HEX Codes**, **RGB Codes**, and **Eye Dropper** selection. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FMxkpn96WpHFyIWp1StsB%252Fcolor_selection.jpg%3Falt%3Dmedia%26token%3De7a016a0-0b8f-4485-bd30-6b2aa80635bd\&width=768\&dpr=4\&quality=100\&sign=c77dfc5f\&sv=2) ### **Panel Color** The **Panel Color** allows you to change the color of the top four widget panels. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FVAWCuqEVWzh1HMDTaYpv%252Fpanel_colors.jpg%3Falt%3Dmedia%26token%3D38a61755-3a9f-4a29-8e6c-c531cc9912ff\&width=768\&dpr=4\&quality=100\&sign=50f81d8c\&sv=2) ### **Background Color** The **Background Color** allows you to change the color of the background of the widget if you're not using a custom background. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FhyiNaE13RJqqvdDfmlmt%252Fbackground_colors.jpg%3Falt%3Dmedia%26token%3D92022b59-a10d-4985-951d-2d2c791d945e\&width=768\&dpr=4\&quality=100\&sign=a5bf25c\&sv=2) ### **Button Color** The **Button Color** allows you to change the color of the button that is directly below the top four panels. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252F7mYmB0FVJqxeb5ZizXlc%252Fimage.png%3Falt%3Dmedia%26token%3Decafeacb-8e0e-420a-b27d-042f7d0a4477\&width=768\&dpr=4\&quality=100\&sign=98d84b76\&sv=2) # Border ### **Overiew** The **Border Panel** affects the edges of all four panels and button of the widget. The orange area shows what the Border Panel affects ### **Custom and None Custom** If you do not wish to have borders, click **None** and disregard the rest of this page. If you would like borders, click **Custom** and follow the rest of this tutorial. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252Fv6vp35JW1mZa9XLgRJK4%252FScreenshot%25202025-01-19%2520at%25201.08.07%2520PM.png%3Falt%3Dmedia%26token%3D54dec655-6170-4aa6-9a97-241e108b8bfc\&width=768\&dpr=4\&quality=100\&sign=e243228e\&sv=2) ### **Border Color** **Border Color** affects the color of the border. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FBR4tLIoAiFEOxGbyOZ61%252Fborder_color.jpg%3Falt%3Dmedia%26token%3D631b6c96-b644-4d31-8cca-961ba838e93d\&width=768\&dpr=4\&quality=100\&sign=34cc00be\&sv=2) Like the previous **Colors Panel**, you can customize colors by using the **Color Selection Panel**, **HEX Codes**, **RGB Codes**, and **Eye Dropper** selection. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FMxkpn96WpHFyIWp1StsB%252Fcolor_selection.jpg%3Falt%3Dmedia%26token%3De7a016a0-0b8f-4485-bd30-6b2aa80635bd\&width=768\&dpr=4\&quality=100\&sign=c77dfc5f\&sv=2) ### **Border Width** **Border Width** affects the width of the border line. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252FWF967CrJBFSrOhOq3wze%252Fborder_width.jpg%3Falt%3Dmedia%26token%3D9e563793-725d-40e4-bdbd-3ba06d0834ab\&width=768\&dpr=4\&quality=100\&sign=99663f92\&sv=2) ### **Border Radius** **Border Radius** affects the roundness of the corners. ![](https://satsterminal.gitbook.io/sats-terminal/~gitbook/image?url=https%3A%2F%2F1880084340-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F4IScksOJO01V2XNJnWQQ%252Fuploads%252F5VrUHpm5pJhhoagBuoys%252Fborder_radius.jpg%3Falt%3Dmedia%26token%3Dcffa883d-58e1-423a-81b7-b52a4601aa3f\&width=768\&dpr=4\&quality=100\&sign=dc1dbc2c\&sv=2) **A value of 0** leaves a sharp right angle corner **∟.** **A value greater than 1** leaves a round corner ⊂. The higher the number, the more round it gets. # Typography ### **Overview** You can customize colors by using the **Color Selection Panel**, **HEX Codes**, **RGB Codes**, and **Eye Dropper** selection.
### **Primary Text Color** **Primary Text Color** is the color of the number values and Button Color (in Light mode).
### **Secondary Text Color** **Secondary Text Color** is the color of the peripheral small text in the widget.
# Updating and Publishing ### **Updating** Clicking **Update Draft** updates.
### **Publishing** Click **Publish Changes** to finalize everything and make them live.
# Embedding Your Widget To embed your widget into your site, use the the HTML code tags in from the Share Widget panel. ### **Head HTML Code ("Add to the \ section")**
Make sure to copy and paste the following code inside your **\\** tags: ``` ``` This is the code that allows for the wallet connect function. ### **Body HTML Code ("Embed Code")**
The body code gets copied and pasted in between the **\\** tags in your HTML page. This is the main widget as it appears in your page. ### **Direct Link** The direct link on it's own will look horrible if linked outside of the **Embed Code**. It is more useful as a means to updating your HTML code.. Direct links without a default rune will be shorter direct links with default rune names **Direct Links WITHOUT a Default Rune set:** ``` [DIRECT_LINK] ``` **Direct Links WITH a Default Rune set:** ``` [DIRECT_LINK]+[DEFAULT•RUNE•NAME] ``` Remember that if you change between a default rune to no default rune and vice versa, to make sure to update the direct link. # What is Earn Earn by Sats Terminal allows users to earn yield on Bitcoin and stablecoins (eg. USDC and USDT) by staking their assets. The platform automatically compares yield options from supported platforms and returns the most competitive interest rates available. Bridging and wrapping steps are handled automatically where required, keeping the experience straightforward for users of both BTC and stablecoins on various chains.
### Key Features * Non-custodial BTC and stablecoin yield flow * Access to a range of supported DeFi and CeFi lenders * Always finds the best rates across available yield providers at the time of request * Earn yield with native BTC # Why Use Earn Earn by Sats Terminal provides a simple way to access yield with bitcoin and stablecoins. The platform aggregates supported yield providers and returns the most competitive interest rates currently available, allowing users to choose a vault without manually comparing providers.
### Key Advantages 1. Best Rates, Automatically Earn reviews supported CeFi and DeFi yield providers and shows the most competitive terms available at the time of your request. 2. No Middlemen, No KYC Users can sign up with an email address. Earn operates without requiring personal identification. 3. Automated Cross-Chain Steps If yield providers operate on different chains, Earn guides the user through the required steps. Bridging and wrapping are handled in-flow where applicable. 4. Speed & Simplicity From option discovery to retrieving principal and interest, the process is designed to be simple and intuitive. 5. Self-Custody Users manage assets through a Privy-backed wallet model, meaning assets are never held in a conventional custodial account. ### Technology and Integrations * Privy-powered wallets secure millions of accounts and billions in transactions. * Earn works with established yield providers and infrastructure components used widely across the ecosystem. * This includes Privy for secure wallet interaction and supported yield providers such as Everstake. # How Earn Works Earn by Sats Terminal allows users to access yield by using bitcoin and stablecoins as principal. The process is designed to be simple and straightforward, with the platform handling the more complex steps in the background. ### 1. Registration & Wallet Setup Users begin by signing up with an email address. No KYC or personal identification is required. When signing in: * A self-custodial wallet is created for the user. * The wallet is secured through Privy’s authentication system, which allows users to access their assets without managing private keys directly. * The wallet can authorize certain automated actions (such as supplying principal) while ensuring the user remains in full control. This setup allows users to yield using BTC and stablecoins without installing a separate wallet or managing seed phrases. ### 2. Staking Configuration Users choose how much BTC or stablecoin they want to use as principal for staking. Earn then checks supported lending providers and displays the loan options currently available. Each staking option includes: * the estimated interest rate * any associated fees * the amount of interest the user will receive * the required principal amount After reviewing the available choices, the user selects the option that best suits their needs. ### 2. Deposit Principal (Bitcoin or stablecoin) Earn provides a unique address for the user’s principal deposit. The user sends BTC or stablecoins to this address directly from their own wallet. \* In the event that the user has already borrowed stablecoin on Sats Terminal and/or deposited Bitcoin or stablecoin to their platform wallet, no deposit will be required. After the transaction is submitted for confirmation on the blockchain, Earn waits for the required confirmations before continuing the process automatically. The system tracks confirmations in real time to ensure secure processing. At each stage, the app provides transparency so users can track the status of their principal. ### 4. Processing Principal (Handled Automatically) After the principal (BTC or stablecoin) deposit is confirmed, Earn handles the required steps to prepare the assets for the selected loan.
This may include: * moving assets to the network used by the yield provider * supplying the principal assets to that provider * initiating staking into vault All of these actions happen automatically in the background. The user does not need to manage wrapping, bridging, or smart contract interactions themselves. Once the principal is supplied, users will start earning yield. \
# Creating Your Account Step 1 - Sign Up * Users register with an email address * Verification is completed via a secure email link * No KYC or personal information is required Step 2 - Wallet Setup * A self-custodial Privy wallet is created automatically * Users do not need to manage private keys or seed phrases * The wallet is used to hold assets Step 3 - Permissions for Staking * To execute a stake, the wallet may request permission to perform specific actions * These permissions are secure and limited and can be reviewed by the user * The user remains in control of their assets at all times # Staking Your First Assets Step-by-step guidance for earning yield using your Bitcoin or stablecoin as principal, fully automated and non-custodial. This guide walks you through the steps of staking using bitcoin and stablecoin as principal. Each stage is designed to be clear and straightforward, with Earn handling the technical work in the background. ### 1. Set your staking preferences Start by choosing the amount of BTC or stablecoin you want to use as principal for staking. Earn will calculate the estimated earnings using estimated Annual Percentage Yield (APY). This helps you understand the expected returns from staking your assets in the respective vaults. ### 2. Review the available loan offer After you set your staking preferences, Earn checks supported staking providers and displays all available vaults based on the terms.
Information includes: * the estimated interest rate * any fees associated with the staking * principal asset details This allows you to review the terms and select the option that best suits your needs before moving forward. ### 3. Deposit your Principal Assets Earn generates a unique Bitcoin or EVM address for your principal asset deposit. You send BTC or stablecoin to this address from your own wallet.
After the transaction is submitted, Earn waits for the required confirmations on the blockchain before continuing. You can track the deposit status in real time while it completes.
Your assets remain in a self-custodial flow until it is supplied to the vault you select. If you choose a custodial vault, the assets will be held by that provider as part of the staking. ### 4. Earn prepares the principal assets After your BTC or stablecoin deposit is confirmed, Earn handles the steps required to prepare the assets for the vault you selected. This may involve moving the assets to the network used by that staking provider and supplying it as principal on your behalf. Throughout this process: * You approve the actions before they occur * Earn only performs the steps needed to complete the loan * You can track the progress directly in the app
If you choose a custodial vault, the assets will be held by that provider as part of the stake. For non-custodial vaults, the assets remains in a self-custodial flow until supplied to the protocol. ### 5. Unstaking your assets When you wish to unstake your asset plus any interest rewards from the vault, Earn handles the steps required to unstake the assets from the vault you staked in. This may involve moving the assets to the network used by that staking provider and withdrawing it to the chain of your choice on your behalf. # Custody & Control Earn is designed to give users a clear and predictable custody experience. You use a self-custodial wallet, approve each required action, and retain visibility and control throughout the staking process. ### Self-custodial wallet When you sign up with your email, a self-custodial wallet is created for you on Sats Terminal.
* No KYC is required to create an account * No passwords or seed phrases to manage * Your assets are held in your own wallet Earn cannot move funds without your approval. This wallet holds your BTC, stablecoins, and any other supported assets used during the staking process. ### Email-based authentication Earn uses simple, passwordless authentication:
1. Enter your email 2. Receive a one-time verification code 3. Enter the code to sign in ### Approvals & permissions Some steps in the staking process require Earn to perform specific actions on your behalf. Before these actions occur, you will be asked to approve the required permissions.
* Permissions are limited to the operations needed for your selected vault * Earn cannot execute transactions without your explicit approval * You can review and manage permissions from your wallet interface
Earn only executes the actions you explicitly approve. ### Custody during staking The custody of your BTC and stablecoin staking depends on the lender you choose: ### Non-custodial vaults Principal assets are supplied to a smart-contract-based protocol. These flows follow on-chain logic and do not rely on a centralized custodian. ### Custodial vaults Some vaults operate custodially. In these cases, your assets are held by the staking provider as part of the staking agreement. Earn clearly indicates the lender type so you can make an informed decision before proceeding. ### Visibility and control Throughout the staking journey: * You can track the status of each step * No actions occur without your approval * You maintain control over your wallet and all assets * You can stake or unstake your assets according to the vault’s terms This structure ensures that you always understand how your assets are handled and what permissions are being used at each stage of the staking process. \
# Automation & Permissions Earn automates the technical steps involved in completing bitcoin and stablecoin staking so you do not need to manage multiple wallets, networks, or smart-contract interactions yourself. These automated steps always require your explicit approval. ### What Earn automates To complete staking, Earn may automate certain operational tasks such as:
* preparing your BTC or stablecoin for the selected vault * supplying the assets on your behalf * delivering assets and interest earned to your wallet once the loan is finalized These steps are shown clearly as they occur. ### Permissions you approve Before Earn performs an automated step, you will be asked to approve the specific action. These permissions: * apply only to the vault you have chosen * do not allow Earn to access unrelated assets in your wallet Earn cannot execute any action without your confirmation. ### What Earn cannot do There are important limits to what Earn is able to access or automate: * Earn cannot withdraw assets from your wallet outside the approved vault operations * Earn cannot alter your staking terms without your involvement * Earn cannot access personal information beyond your email address * Earn cannot intervene in a vault held by a custodial staking provider All actions rely on user approval and staking provider rules. ### Visibility and transparency Throughout the process, the Earn interface shows: * which step is being performed * what action is about to occur * when a permission is required * when assets has been supplied to the vault This ensures you always understand what is happening behind the scenes. \
# Vaults & Counterparty Risk Earn connects users to a range of staking providers. Each provider operates under its own custody model, risk profile, and terms. Understanding these differences helps you choose the vault option that fits your needs. ### Non-custodial vaults Some vaults use smart-contract-based systems to manage assets and issuerewards . With these vaults: * asset is supplied to the protocol’s smart contracts * vault terms are enforced on-chain * interest and terms follow protocol-defined rules ### Considerations Non-custodial lending carries technical and market risks, including: * smart-contract vulnerabilities * liquidity constraints * protocol-specific parameters such as interest models or reward distribution While these systems are transparent and on-chain, they still involve inherent risks. ### Custodial vaults Other vaults operate using a custodial model. In these cases, assets are held directly by the vault provider as part of the staking agreement. ### Considerations Custodial vaults introduces counterparty risk: * asset safety depends on the provider’s operational practices and solvency * staking terms and servicing follow the provider’s internal policies * the provider decides how assets are managed and stored Custodial providers may offer different rates or features, but users should evaluate the risks that come with centralized custody. ### How Earn presents lenders Earn does not hold assets on behalf of users. Instead, it provides access to supported vault providers and clearly shows whether a provider is: * custodial * non-custodial * operating on a specific network * offering a particular staking structure This transparency allows you to choose a vault based on your own preferences, risk tolerance, and desired staking features. ### Your responsibility as a staker Before entering a vault, users should consider: * the vault’s custody model * the staking terms and conditions * the risks associated with the type of vault selected * how staking rewards may be affected by market volatility Earn provides the information needed to make an informed decision, but the choice of vault and yield structure ultimately rests with the user. \ \
# Protocol & Network Risk Earn interacts with on-chain systems and, in some cases, multiple blockchain networks depending on the vault you select. These systems carry distinct risks and operational considerations that are important to understand. ### Bridging between networks Some vaults operate on networks outside the blockchains you might be used to. When a vault requires assets to be used on another network, Earn may bridge assets as part of the process. Bridging introduces certain considerations: * it relies on infrastructure that connects different blockchain networks * network delays or congestion may affect processing times * all bridging systems carry inherent technical risk, including potential vulnerabilities Earn only performs bridging when required for the vault you choose. Bridging steps are presented clearly so you can track progress in real time. ### Smart-contract protocol risk When you select a non-custodial vault, staking is managed through that provider’s smart contracts. As with any on-chain system: * smart contracts may contain bugs or unintended behavior * protocol governance and design choices can influence risk * market conditions may affect liquidity and rewards These risks apply to all smart-contract systems. ### Earn’s approach Earn aims to simplify interactions with on-chain systems while maintaining transparency: * bridging and protocol steps are automated when needed * each step is shown in the interface * no actions occur without your approval Earn does not remove protocol or network risk, but the platform makes these processes visible so you understand how your assets are being handled. \
# How Interest Rates Work Interest rates determine the rewards of staking and play a significant role in the overall incentives you receive for staking into a vault. Understanding how rates behave helps you make more informed staking decisions. ### Why interest rates exist When you stake BTC and stablecoin, you earn interest from the vault in exchange for access to your liquidity. The rate you receive is determined by the vault’s model, market conditions, and the depth of liquidity. ### What affects interest rates Interest rates can move for several reasons, including: * Liquidity supply: lower supply may increase rates. * Available liquidity: more supply may lower rates. * Market conditions: volatility or rapid inflows/outflows can affect utilization. * Vault parameters: each vault defines its own rules for adjusting rates. Rates are not static; they evolve based on how the market is behaving. ### Variable (Floating) interest rates A variable (or floating) rate adjusts over time. Most crypto-backed vaults use variable models because they react to changing market conditions. Variable rates may: * decrease when demand is low * increase when liquidity is scarce or utilization is high * update frequently depending on vault mechanisms Variable rates offer higher rates during favorable conditions but can decrease unexpectedly. ### Fixed interest rates Some vaults offer fixed rates for staking. A fixed rate remains the same for the duration of the staking period and does not change with market conditions. Fixed rates may: * provide predictability and easier planning * be lower than floating rates during stable market periods ### Why rate movement matters Changing interest rates can affect: * Total interest received over the life of the stake * Annualised Percentage Yield (APY), since interest accrues * Strategy risk, especially for users staking with borrowed assets Monitoring your staked vault and understanding how rates behave is important during active yield farming. ### How Borrow presents interest rates * shows each vault’s current rate before you stake * displays your active rate and metrics in the dashboard * makes rate behavior visible without managing rates on your behalf This gives you clarity while keeping control in your hands. # Choosing an Interest Rate Earn helps you compare available vault options across supported providers so you can select the interest rate model and terms that best fit your needs before staking your assets. ### What Borrow displays during loan creation When staking into a vault, Earn presents: * the current interest rate offered by each vault * whether the rate is variable or fixed (if available) * the required asset for the chosen loan * any fees included in staking This allows you to evaluate opportunity, predictability, and risk across vaults. ### Choosing a variable (floating) rate A variable rate may suit you if: * you want the highest possible rate today * you’re comfortable with rates that may move * you expect increasing yield Considerations * variable rates can decrease during market volatility * decreased interest rates affect estimated earnings * stakers should track how rate movement affects their overall finance strategy ### Choosing a fixed rate A fixed rate may suit you if: * you prefer predictable staking yield * you want to avoid fluctuations during volatility * you are risk-averse or running a loan-yield strategy Considerations: * fixed rates may be lower than variable rates * availability depends entirely on the vault provider * fixed-rate yield are less common in crypto markets ### After your asset is staked Once active: * your interest rate follows the model defined by the vault * variable rates may move up or down over time * Earn displays your current APY and value locked in the dashboard ### Earn’s role Earn provides visibility and comparison tools when you stake assets. Rate management decisions remain with the user. # Swap This page explains how to perform swaps inside the Spark ecosystem using Sats Terminal. Swapping tokens on Spark through Sats Terminal is designed to feel natural even for users unfamiliar with Bitcoin-native trading. The interface focuses on simplicity: you select the token, specify the amount, adjust your preferences, and submit the transaction through your wallet. Behind this lightweight workflow is a routing engine that automatically seeks the best available price across Spark liquidity. {% embed url="" %} *** ### **Connecting Your Wallet** Everything begins with connecting your wallet, which activates the swap panel and unlocks your balances. Sats Terminal supports Spark Wallet, Xverse, and even lets you create a new Spark Wallet instantly within the interface. This flexibility means that both experienced users and newcomers can start swapping without additional setup.
Once connected, your BTC and token balances sync automatically, ensuring all swap calculations reflect real on-chain data. *** ### **Preparing Your Swap** The swap interface is built for clarity. You choose which token you want to buy or sell, and Sats Terminal displays the estimated output, route, and expected slippage. Percentage shortcuts for BTC (25%, 50%, Max) make it easy to commit a part of your balance without typing numbers manually. You can swap in either direction: * **BTC → Spark token** * **Spark token → BTC** A single button flips the direction, which is useful if you're rebalancing or exiting a position quickly. {% hint style="info" %} Auto Routing is enabled by default, giving you the most efficient path. Manual Routing is available for advanced users wanting full control over pools and liquidity paths. {% endhint %} *** ### **Slippage & Routing Settings** Small adjustments to slippage can be crucial when dealing with volatile tokens or low-liquidity pairs.\ You are free to set: * Default recommended slippage * Custom slippage (useful for rapid market movement) * Auto routing for best execution * Manual routing for strategic control This combination allows beginners to keep things simple, while giving traders room to personalize their strategy. *** ### **Executing the Swap** Once settings are configured, confirm the swap. Your wallet will open a signing request showing the transaction details. After you approve the transaction, Spark’s settlement layer finalizes your swap on Bitcoin. The interface will show a confirmation once the swap is fully executed. Swapping is intentionally streamlined - the goal is to reduce friction, while still providing enough transparency and control to satisfy experienced traders. # Pro Charts The Pro section is where Spark’s market data becomes fully transparent. The Pro dashboard transforms raw blockchain data into an elegant market analytics environment. Instead of overwhelming users with complex charts, it organizes information around the essentials: price action, liquidity, holders, and real-time transactions. Whether you are exploring a new Spark token or evaluating long-term growth, Pro mode gives you all the tools you need in a clean, readable layout. {% embed url="" %} *** ### **Price Charts & Timeframes** At the top of the interface is the main price chart. You can switch between 1-hour, 1-day, 1-week, and 1-month views. Each timeframe highlights different market behaviors, from short-term volatility to structural trends. Candlestick movements, price stabilization zones, and momentum shifts are immediately visible.
The chart updates in real time, pulling its data directly from Spark’s on-chain activity. *** ### **Market Overview Metrics** Under the chart, you’ll find a compact but informative block containing: * Market cap * 24h trading volume * Total value locked (TVL) * Current token price * 24h price change
This section helps you instantly determine the token’s liquidity health and market interest. Large swings, quiet periods, sudden jumps in activity - everything becomes easier to interpret when paired with recent volume and TVL information. *** ### **Real-Time Transaction Feed** Every transaction involving the token appears in a live feed. This includes buys, sells, transfers, and interactions from major participants. Each entry lists the amount, timestamp, wallet address, token quantity, BTC value, and a direct link to SparkScan. Watching this feed gives you a sense of which addresses are active, whether whales are accumulating or selling, and how liquidity behaves during peak activity. *** ### **Holder Distribution** The holders tab reveals how widely distributed the token is. Each entry includes an address, its balance, and share of supply. Highly decentralized tokens tend to have a healthier market structure, while concentrated holdings near the top may indicate whales or early investors. The combination of charts, metrics, feed, and holders gives you a complete picture of the token’s current standing - helping you make informed decisions without leaving the page. # Bubble Map This page explains how the Bubble Map visualizes token ownership and relationships between wallets. The Bubble Map provides a visual interpretation of how Spark token supply is distributed across wallets. Rather than relying solely on lists and numbers, it converts wallet data into a system of interconnected nodes that highlight both the size of holdings and the relationships among them. *** ### **Visual Structure** Each bubble represents a wallet, with its size proportional to the token balance it holds. Bigger bubbles mean larger holders, while smaller ones represent regular users. This makes it easy to recognize whales or clusters of early participants at a glance.
{% hint style="info" %} When bubbles are connected, it means that those wallets interacted with each other through transfers or other on-chain operations. This builds an intuitive view of the network around a token. {% endhint %} *** ### **Exploring the Network** Clicking a bubble opens detailed information: * Wallet address * Balance * Share of total supply * A list of connected wallets A single click can reveal entire clusters, helping identify linked wallets, multi-address whales, or distribution patterns. {% hint style="info" %} If you want a deeper view, each wallet can be opened on SparkScan through a direct link. {% endhint %} *** ### **Why It Matters** The Bubble Map adds transparency to the Spark ecosystem.\ It helps: * Understand decentralization * Identify whales * Detect suspicious patterns * Track how supply changes over time Instead of reading one-dimensional data, the Bubble Map provides a living picture of the token’s ecosystem. # Explore Section The Explore section is designed to help users discover Spark tokens, review their performance, and compare liquidity across the entire ecosystem - all from a single page. Explore acts as the main directory for Spark assets. Instead of navigating through individual tokens one by one, you can see the full market landscape in a single, structured view. For traders, this page is often the starting point when searching for opportunities or tracking activity. {% embed url="" %} *** ### **Understanding the Pools List** Each row in the Explore table presents a compact summary of a Spark token or liquidity pool, including: * Token name and pair * Current price and its 24h change * TVL indicating available liquidity * 24h volume showing trading activity * Number of holders * A visual trend indicator representing recent price direction
This layout makes it easy to identify which assets are gaining traction and which are cooling off. *** ### **Filtering & Sorting** You can sort the table by any metric - price movement, liquidity, volume, or number of holders. This allows you to quickly surface the most relevant tokens based on your goal: discovering new assets, identifying stable pools, or monitoring high-activity zones. *** ### **Fast Navigation to Pro View** Clicking any row opens the token’s Pro view, letting you instantly dive deeper into charts, transactions, and holder structure. This smooth navigation makes it easy to shift from discovery to analysis without losing context. *** ### **Why Explore Is Useful** The Explore section brings transparency to Spark’s entire ecosystem. It lets you understand which tokens dominate liquidity, which are becoming more active, and how the ecosystem is evolving over time. For both newcomers and experienced traders, it’s the most efficient way to get a clear overview of the market.