# Satora Swaps Docs - [Welcome to Satora Swaps](https://docs.satora.io/index.md): Instant, trustless Bitcoin to EVM token swaps with Lightning Network, Arkade, and on-chain support - [Getting Started](https://docs.satora.io/getting-started.md): Quick start guide for developers integrating Satora Swaps - [API, SDK & Iframe](https://docs.satora.io/api-sdk.md): Integrate Satora Swaps into your application using our TypeScript SDK, REST API, or iframe embed - [Setup](https://docs.satora.io/setup/setup.md): Initialize the SDK and verify API connectivity - [Key Management & Mnemonic](https://docs.satora.io/setup/wallet-mnemonic.md): Self-custodial key setup and management - [API Keys](https://docs.satora.io/setup/api-keys.md): Optional API keys for swap attribution and custom fee markup - [Supported Tokens & Pairs](https://docs.satora.io/quotes-rates/supported-tokens.md): List of supported tokens and trading pairs - [Get Exchange Rate](https://docs.satora.io/quotes-rates/exchange-rate.md): Retrieve current exchange rates and quotes for swap pairs - [BTC → EVM](https://docs.satora.io/create-swaps/btc-to-evm.md): Swap any BTC variant (Lightning, on-chain, Arkade) to any ERC-20 token on supported EVM chains - [Onchain → tBTC](https://docs.satora.io/create-swaps/onchain-to-tbtc.md): Swap on-chain Bitcoin (L1) to tBTC on Ethereum or Arbitrum. - [USDT to Lightning](https://docs.satora.io/create-swaps/evm-to-btc.md): Buying BTC with USDC or USDT - [Onchain → Arkade](https://docs.satora.io/create-swaps/onchain-to-arkade.md): Create a swap from on-chain Bitcoin to Arkade VTXOs for instant, low-fee transactions. - [Lightning ↔ Arkade](https://docs.satora.io/create-swaps/lightning-arkade.md): Swap between Lightning and Arkade VTXOs in both directions for instant, low-fee Bitcoin transfers. - [Refund Onchain HTLC](https://docs.satora.io/handle-failures/refund-onchain-htlc.md): Refund funds locked in an onchain Bitcoin HTLC when a swap fails or times out. - [Refund EVM HTLC](https://docs.satora.io/handle-failures/refund-evm-htlc.md): Refund tokens locked in an EVM HTLC smart contract when a swap fails or times out. - [Recover Swaps from Seed](https://docs.satora.io/handle-failures/recover-swaps-from-seed.md): Restore and recover pending swaps using your mnemonic seed phrase. - [Error Codes](https://docs.satora.io/handle-failures/error-codes.md): Complete reference of all API and SDK error codes with solutions. - [React Native Setup](https://docs.satora.io/setup/react-native.md): Configure the Satora Swaps SDK for React Native with persistent storage using MMKV. - [Hash Time-Locked Contracts (HTLC)](https://docs.satora.io/advanced/htlc.md): How HTLCs enable trustless atomic swaps - [Swap State Machine](https://docs.satora.io/advanced/state-machine.md): Understanding swap states and transitions - [Health check endpoint](https://docs.satora.io/api-reference/health.md) - [Return the current git tag and commit hash.](https://docs.satora.io/api-reference/version.md) - [Return the current cached Median Time Past (MTP) and tip height.](https://docs.satora.io/api-reference/mtp.md) - [Get a quote for swapping BTC to/from EVM tokens](https://docs.satora.io/api-reference/quote.md): Specify exactly one of source_amount or target_amount. Amounts are in the smallest unit of the respective token (satoshis for BTC, raw units for EVM tokens). - [Return all supported swap pairs with their limits (in satoshis) and base fee percentages.](https://docs.satora.io/api-reference/swap-pairs.md) - [Get list of available tokens for swaps.](https://docs.satora.io/api-reference/tokens.md): Optionally pass `source_chain` + `source_token` **or** `target_chain` + `target_token` to filter the response to valid counterparty tokens. - [Get supported EVM chains](https://docs.satora.io/api-reference/evm-tokens/chains.md) - [Get available EVM tokens from 1inch for supported chains](https://docs.satora.io/api-reference/evm-tokens.md) - [Create a chain-agnostic Lightning-to-EVM swap.](https://docs.satora.io/api-reference/swap/lightning/evm.md): Flow: 1. User pays the returned hold invoice; the payment is held. 2. Server funds an HTLCErc20 locked to the same hash. 3. User claims the HTLC (gasless), revealing the preimage. 4. Server settles the held payment with the revealed preimage. - [Create a chain-agnostic Bitcoin-to-EVM swap.](https://docs.satora.io/api-reference/swap/bitcoin/evm.md) - [Create a chain-agnostic Arkade-to-EVM swap.](https://docs.satora.io/api-reference/swap/arkade/evm.md) - [Claims an EVM-targeted swap gaslessly via the HTLCCoordinator contract.](https://docs.satora.io/api-reference/swap/id/claim-gasless.md): Supports Arkade-to-EVM, Lightning and Bitcoin-to-EVM swaps. The server submits `coordinator.redeemAndExecute` on the client's behalf, using the client's EIP-712 signature and secret. - [Returns the gasless claim data for an EVM-targeted swap.](https://docs.satora.io/api-reference/swap/id/redeem-and-swap-calldata.md): For non-WBTC targets: fetches fresh 1inch DEX calldata with `receiver = destination`. For WBTC-direct targets: returns only the gasless fee and calls_hash (no DEX data). - [Create a chain-agnostic EVM-to-Lightning swap.](https://docs.satora.io/api-reference/swap/evm/lightning.md): Flow: 1. User funds the HTLCErc20 (via the coordinator; locked to the invoice's payment hash) 2. Once the funding is final, the server pays the invoice; the settled payment reveals the preimage 3. Server claims the HTLC with the preimage - [Create a chain-agnostic EVM-to-Bitcoin swap.](https://docs.satora.io/api-reference/swap/evm/bitcoin.md) - [Create a chain-agnostic EVM-to-Arkade swap.](https://docs.satora.io/api-reference/swap/evm/arkade.md) - [Fund an EVM-sourced swap gaslessly via Permit2.](https://docs.satora.io/api-reference/swap/id/fund-gasless.md): The server submits the `executeAndCreateWithPermit2` transaction on the depositor's behalf, pulling tokens via the depositor's Permit2 signature. If an EIP-2612 permit is provided, the server first submits that to approve the Permit2 contract. - [Returns structured data for funding an EVM-to-BTC swap via Permit2.](https://docs.satora.io/api-reference/swap/id/swap-and-lock-calldata-permit2.md): Instead of pre-encoded calldata, this returns the individual components so the SDK can construct the Permit2 EIP-712 signature and `executeAndCreateWithPermit2` calldata client-side. - [Create a new Lightning-to-Arkade swap.](https://docs.satora.io/api-reference/swap/lightning/arkade.md): The user pays a BOLT11 hold invoice and receives Arkade VTXOs. Flow: 1. User pays the returned hold invoice (the payment is held, not settled) 2. Server creates an Arkade VHTLC locked to the same hash 3. User claims the VHTLC with their secret, revealing it 4. Server settles the held Lightning payme… - [Create a new Arkade-to-Lightning swap.](https://docs.satora.io/api-reference/swap/arkade/lightning.md): The user locks Arkade VTXOs in a VHTLC and receives BTC on their Lightning invoice. Flow: 1. User funds the returned Arkade VHTLC (locked to the invoice's payment hash) 2. Server pays the invoice; the settled payment reveals the preimage 3. Server claims the VHTLC with the preimage - [Create a new Bitcoin (on-chain) to Arkade swap request](https://docs.satora.io/api-reference/swap/bitcoin/arkade.md): The user provides an on-chain BTC amount to swap and receives Arkade VTXOs. Flow: 1. User sends BTC to the Taproot HTLC address returned 2. After 1 confirmation, server creates Arkade VHTLC for user 3. User claims Arkade VHTLC with secret, revealing it 4. Server claims on-chain BTC with the revealed… - [Get swap status and details by ID](https://docs.satora.io/api-reference/swap/id.md) - [Recover swaps by deriving user_id keys from an Xpub](https://docs.satora.io/api-reference/swap/recover.md): This endpoint allows clients to recover their swap history after importing a mnemonic. The client provides an Xpub they used to derive `user_id`s, and the server derives `user_id` keys at m/9419/121923/ from the requested start index until the server-owned gap limit or scan cap is reached. - [Collaboratively refund an EVM HTLC before timelock expiry.](https://docs.satora.io/api-reference/swap/id/collab-refund-evm.md): The client signs a coordinator-level `CollabRefund` EIP-712 message authorizing the refund parameters. The server cosigns with an HTLC-level `Refund` signature (as claimAddress, waiving the timelock) and submits the transaction on-chain. - [Get EIP-712 parameters for collaborative EVM HTLC refund.](https://docs.satora.io/api-reference/swap/id/collab-refund-evm/params.md): Returns the addresses, amounts, and struct fields the client needs to construct and sign the `CollabRefund` EIP-712 typed data. The client signs this, then POSTs the signature to the collab-refund-evm endpoint. - [Returns calldata to refund an expired EVM-to-Arkade HTLC via the coordinator.](https://docs.satora.io/api-reference/swap/id/refund-and-swap-calldata.md): Calls `refundTo` — refunds the lock asset (tBTC/WBTC, or the native coin on a native-lock chain) to the depositor. Permissionless after the timelock expires. - [Collaboratively refund spendable VTXOs.](https://docs.satora.io/api-reference/swap/arkade-evm/id/collab-refund.md): The client builds an offchain transaction (ark_tx + checkpoints) spending the VHTLC via the `refund_script` leaf, signs as sender, and sends the partially-signed PSBTs here. The server cosigns as receiver and returns the countersigned PSBTs. The client then submits to Arkade for the server (3rd) sig… - [Collaboratively refund recoverable VTXOs via the delegate batch flow.](https://docs.satora.io/api-reference/swap/arkade-evm/id/collab-refund-delegate.md): The client prepares delegate PSBTs (intent_proof + forfeits) spending the VHTLC via the `refund_script` leaf, signs as sender, and sends the partially-signed PSBTs here. The server cosigns as receiver and returns the countersigned PSBTs. The client then calls `/api/delegate/settle` to complete the b… - [Get the delegate cosigner public key.](https://docs.satora.io/api-reference/delegate/cosigner-pk.md): Clients need this key when preparing delegate PSBTs so the backend can participate in the batch ceremony as a cosigner. - [Settle a delegated batch.](https://docs.satora.io/api-reference/delegate/settle.md): The client prepares and signs delegate PSBTs (intent + forfeits), then POSTs them here. The backend reconstructs the `Delegate` struct and runs the full Ark batch ceremony on the client's behalf. - [Return the configured support agent npubs.](https://docs.satora.io/api-reference/support-agents.md) - [Logo, Motto & Colors](https://docs.satora.io/design/logo-colors.md): Satora logo usage, brand motto, and color palette - [Typography & Spacing](https://docs.satora.io/design/typography.md): Font families, type scale, spacing tokens, and icon usage - [Buttons](https://docs.satora.io/design/buttons.md): Button system - variants, states, and sizing - [Textfields & Inputs](https://docs.satora.io/design/textfields-inputs.md): Input styles, focus states, and field patterns - [Media Kit](https://docs.satora.io/design/media.md): Official logos, icons, and assets for press and partner use - [General](https://docs.satora.io/faq/general.md): General questions about Satora Swaps - [Integration](https://docs.satora.io/faq/integration.md): Questions about integrating the Satora Swaps SDK - [Gasless & Fees](https://docs.satora.io/faq/gasless-and-fees.md): Questions about gasless execution and fee structure - [Security](https://docs.satora.io/faq/security.md): Questions about Satora Swaps security and fund safety - [Troubleshooting](https://docs.satora.io/faq/troubleshooting.md): Common issues and how to resolve them ## OpenAPI Specs - [openapi](/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.