# Quickstart ## Intergate Satoshi Protocol ### Requirements * React 17.0.0 or higher Satoshi BTC Wallet is a toolkit that enables Bitcoin usage on the NEAR blockchain through the Satoshi protocol. ### Demo Demo Address: Demo Source: ### Install GitHub: ``` pnpm install btc-wallet # or yarn add btc-wallet ``` ### Method #### `1.BtcWalletSelectorContextProvider` and `setupBTCWallet` Initialize and integrate BTC wallet with NEAR wallet selector. ``` // 1. Setup wallet selector with BTC wallet module import { setupWalletSelector } from '@near-wallet-selector/core'; import { setupBTCWallet, setupWalletSelectorModal } from 'btc-wallet'; const selector = await setupWalletSelector({ network: 'mainnet', // or 'testnet' debug: true, modules: [ setupBTCWallet({ iconUrl?: string, // optional: custom wallet icon URL deprecated?: boolean, // optional: mark as deprecated autoConnect?: boolean, // optional: enable auto-connect, defaults to true syncLogOut?: boolean, // optional: sync logout across tabs, defaults to true env?: 'mainnet' | 'testnet' | 'private_mainnet' | 'dev' // optional: defaults to NEAR network environment }), // setup other wallets... ], }); // 2. Setup wallet selector modal // Note: For enhanced functionality, use setupWalletSelectorModal exported from btc-wallet // If using setupModal from @near-wallet-selector/modal-ui, the showChainGroups and showWalletUIForNearAccount parameters below are not supported setupWalletSelectorModal(selector, { contractId: 'xxx.near', showChainGroups?: boolean, // optional: show chain group selection, defaults to true showWalletUIForNearAccount?: boolean, // optional: show wallet UI for regular NEAR accounts, defaults to true env?: 'mainnet' | 'testnet' | 'private_mainnet' | 'dev', // optional: defaults to NEAR network environment draggable?: boolean, // optional: enable button dragging, defaults to true initialPosition?: { right: string; bottom: string }, // optional: initial button position, defaults to { right: '20px', bottom: '20px' } buttonSize?: string, // optional: button size, defaults to '60px' mobileButtonSize?: string, // optional: mobile button size, defaults to '40px' }); // 3. Wrap your app with BtcWalletSelectorContextProvider import { BtcWalletSelectorContextProvider } from 'btc-wallet'; import '@near-wallet-selector/modal-ui/styles.css'; function App() { return ( {/* Your application components */} ); } ``` #### `2.executeBTCDepositAndAction` Execute a native BTC deposit to receive corresponding BTC tokens on NEAR through the Satoshi bridge. You must provide either `action` or `amount`, but not both. ``` interface ExecuteBTCDepositAndActionParams { // Option 1: For dApp one-click BTC deposit and action action?: { receiver_id: string; // receiver account on NEAR amount: string; // amount to deposit msg: string; // message for the transaction }; // Option 2: For direct Satoshi bridge deposit amount?: string; // amount to deposit to Satoshi bridge // Common optional parameters feeRate?: number; // optional: custom fee rate for the BTC transaction env?: 'mainnet' | 'testnet' | 'private_mainnet' | 'dev'; // optional: defaults to NEAR network environment pollResult?: T; // optional: whether to poll for transaction result registerDeposit?: string; // optional: whether to register deposit,default 0.000125 NEAR newAccountMinDepositAmount?: boolean; // default is true, if true, new account minimum deposit BTC amount 1000sat, otherwise 0 registerContractId?: string; // if registerContractId is provided, it will be used to register the contract, otherwise it will be the default contract id } // Example 1: dApp one-click BTC deposit await executeBTCDepositAndAction({ action: { receiver_id: 'token.near', amount: '1000000', msg: 'ft_transfer_call message' // ft_transfer_call message }, registerDeposit: '100000000000000000000000', // default 0.000125 NEAR, you can set it according to your needs }); // Example 2: Direct Satoshi bridge deposit await executeBTCDepositAndAction({ amount: '1000000', // amount to deposit to Satoshi bridge feeRate: 5 }); ``` #### `3.getBtcBalance` Get the native BTC balance for a given Bitcoin address. ``` import { getBtcBalance } from 'btc-wallet'; const balance = await getBtcBalance(address: string); // Returns balance in satoshis ``` #### `4.getDepositAmount` Calculate the amount of BTC tokens that can be received on NEAR after depositing native BTC through Satoshi Bridge. This takes into account bridge fees and minimum deposit requirements. ``` import { getDepositAmount } from 'btc-wallet'; // Calculate receivable amount const result = await getDepositAmount( amount: string, // Amount in satoshi units options?: { env?: 'mainnet' | 'testnet' | 'private_mainnet' | 'dev', // Optional: Defaults to NEAR network environment newAccountMinDepositAmount?: boolean // default is true, if true, new account minimum deposit amount 1000sat, otherwise 0 } ); // Returns interface DepositAmountResult { depositAmount: number; // Original deposit amount to be sent receiveAmount: number; // Amount to be received after deducting fees and repayments protocolFee: number; // Protocol fee repayAmount: number; // Amount to repay if there's debt newAccountMinDepositAmount: number; // Minimum deposit amount for new accounts } When making a deposit: - The user sends the `depositAmount` of BTC - After deducting protocol fees and repayment amounts, the user receives `receiveAmount` on NEAR - For new accounts, the function will throw an error if the `receiveAmount` is less than the minimum required amount ``` #### `5.getWithdrawTransaction` Get transaction for withdrawing BTC from NEAR to a specified bitcoin address. ``` import { getWithdrawTransaction } from 'btc-wallet'; const transaction = await getWithdrawTransaction({ btcAddress: string, // Target bitcoin address amount: string, // Amount to withdraw in satoshi units env?: 'mainnet' | 'testnet' | 'private_mainnet' | 'dev' // Optional: Defaults to NEAR network environment }); ``` The estimated amount will be less than the input amount due to: * Bridge fees * Minimum deposit requirements * Protocol fees ### Github Link {% embed url="" %} ### Error Code | Error Code | Status | Description | | ---------- | ------ | ------------------------------------- | | 0 | Normal | Received Tx | | 1 | Normal | Registered | | 2 | Normal | MPC Signed | | 3 | Normal | User Txs Sent Success | | 4 | Normal | Register Sent, need verify | | 5 | Normal | User Txs Sent, need verify | | 6 | Normal | MPC trigger sign tx sent, need verify | | 50 | Error | deposit amount less | | 51 | Error | withdraw fee less | | 97 | Error | User txs expired | | 98 | Error | User txs nonce error | | 99 | Error | User near less | | 101 | Reject | Satoshi Protocol Nonce Error | | 102 | Reject | Satoshi Protocol Arrears Error | | 103 | Reject | Too Many Logs on Near Chain | | 104 | Reject | Withdraw Address Error | | 105 | Reject | Previous near txs has not been signed | | 106 | Reject | Satoshi TX signature error | | 107 | Reject | Bridge Less Balance | | 108 | Reject | Repeat Satoshi Tx | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.satos.network/getting-started/quickstart.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.