# StxCity SDK StxCity SDK is a powerful and easy-to-use library for interacting with the StxCity Protocol. It provides a set of tools to seamlessly integrate StxCity functionality into your applications. ## Table of Contents 1. [Installation](#installation) 2. [Configuration](#configuration) 3. [Usage](#usage) 4. [Available Functions](#available-functions) 5. [Public Methods](#public-methods) 6. [Types](#types) 7. [Troubleshooting](#troubleshooting) 8. [License](#license) ## Installation Install the StxCity SDK using npm: ```bash npm install stxcity-sdk ``` ## Usage Here's a step-by-step guide to implement the StxCity SDK in your project: ### 1. Import the SDK: ```typescript import { StxCitySDK } from 'stxcity-sdk'; ``` ### 2. Initialize the SDK: #### Option 1: Use a config object ```typescript const stxcityConfig = { HIRO_API_KEY: "", // get it from https://platform.hiro.so/ STXCITY_API_HOST: 'https://stx.city', STACKS_NETWORK_API_HOST: 'https://api.mainnet.hiro.so' } const stxcitySDK = new StxCitySDK(new StacksMainnet(), stxcityConfig) ``` #### Option 2: Use .env file ``` STXCITY_API_HOST="https://stx.city" STACKS_NETWORK_API_HOST="https://api.mainnet.hiro.so" HIRO_API_KEY="" // get it from https://platform.hiro.so/ ``` and then initialize the SDK like this: ```typescript const stxcitySDK = new StxCitySDK(new StacksMainnet()) ``` ## Available functions ### Buy Bonding Token ```typescript try { const params: BuyBondingTokenParams = { stxAmount: 100, // Replace with actual amount dexContractId: 'dexId', // Replace with actual dex contract ID tokenContractId: 'tokenContractId', // Replace with actual token contract ID tokenSymbol: "symboltoken", // Replace with actual token symbol senderAddress: "ST3JH3Y...XYZ", // Replace with sender address slippage: 50, // Replace with your slippage onFinish: (data) => { console.log("Buy token:", data); }, onCancel: () => { console.log("Buy token canceled"); }, }; await StxCitySDK.buyBondingToken(params); } catch (error) { console.error("Error buying bonding token:", error); } ``` Note: Already check valid bonding curve contract inside this function ### Sell Bonding Token ```typescript try { const params: SellBondingTokenParams = { tokenAmount: 2000000, // Replace with actual amount token dexContractId: 'dexId', // Replace with actual dex contract ID tokenContractId: 'tokenContractId', // Replace with actual token contract ID tokenSymbol: 'symboltoken', // Replace with actual token symbol senderAddress: "ST3JH3Y...XYZ", // Replace with sender address slippage: 50, // Replace with your slippage onFinish: (data) => { console.log("Sell token success:", data); }, onCancel: () => { console.log("Sell token canceled"); }, }; await StxCitySDK.sellBondingToken(params); } catch (error) { console.error("Error selling bonding token:", error); } ``` Note: Already check valid bonding curve contract inside this function ### Check Valid Bonding Token Check if the bonding curve contract is valid to avoid scam/fake tokens. ```typescript const isValid = await StxCitySDK.checkValidBondingToken('dexContractId', 'tokenContractId'); ``` ### Get Bonding Token ```typescript let page = 1; let limit = 40 const bondingTokenData = await StxCitySDK.getBondingToken(page, limit); ``` `limit` max is 100 ### Search Token ```typescript let params:SearchTokenParams = { keyword : 'searchKeyowrd', // Replace with actual search keyword tokenContract: 'xxxxx-stxcity' // Replace with actual token contract ID you want to search } const data = await StxCitySDK.searchToken(params) ``` ## Disclaimer - The StxCity SDK is provided "as is" without any warranty. Use it at your own risk. - There are many malicious or fake bonding curve contracts on the Stacks blockchain. Please make sure you are using the correct bonding curve contract or user wallet can be drained. - Call `checkValidBondingToken` function to check if the bonding curve contract is valid. ## Public Methods The following public methods are available in the `StxCitySDK` class: ### `buyBondingToken(params: BuyBondingTokenParams): Promise` Buys a bonding token with the specified parameters. ### `sellBondingToken(params: SellBondingTokenParams): Promise` Sells a bonding token with the specified parameters. ### `getBondingToken(page: number, limit: number): Promise` Fetches bonding token data for the specified page and limit. ### `searchToken(params?: SearchTokenParams): Promise` Searches for tokens based on the provided parameters. ## Types The following types and interfaces are exported from the `types.ts` file: ### `StxCityContext` ```typescript export interface StxCityContext { validAPIKey: boolean; network: StacksNetwork; } ``` ### `BondingTokenItem` ```typescript export interface BondingTokenItem { id: number; token_contract: string; dex_contract: string; progress: number; name: string; tx_id: string; symbol: string; decimals: number; supply: number; logo_url: string; holders: number; deployed_at: Date; stx_paid: number; description: string; xlink: string; homepage: string; telegram: string; discord: string; status: string; target_AMM: string; chat_count: number; txs_count: number; trading_volume: number; target_stx: number; price?: number; price_24h_changes?: number; token_to_dex?: number; token_to_deployer?: number; stx_to_dex?: number; stx_buy_first_fee?: number; } ``` ### `NormalTokenItem` ```typescript export interface NormalTokenItem { contract_id: string; name: string; logo_url: string; symbol: string; homepage: string; supply: number; decimals: number; holders: number; tx_id: string; deployed_at: Date; } ``` ### `BondingTokenData` ```typescript export interface BondingTokenData { trending: BondingTokenItem[]; new: BondingTokenItem[]; completed: BondingTokenItem[]; all: BondingTokenItem[]; total: number; page: number; limit: number; } ``` ### `BuyBondingTokenParams` ```typescript export interface BuyBondingTokenParams { stxAmount: number; dexContractId: string; tokenContractId: string; tokenSymbol: string; senderAddress: string; slippage: number; stacksProvider?: StacksProvider; onFinish?: (data: any) => void; onCancel?: () => void; } ``` ### `SellBondingTokenParams` ```typescript export interface SellBondingTokenParams { tokenAmount: number; dexContractId: string; tokenContractId: string; tokenSymbol: string; senderAddress: string; slippage: number; stacksProvider?: StacksProvider; onFinish?: (data: any) => void; onCancel?: () => void; } ``` ### `SearchTokenType` ```typescript export interface SearchTokenType { ads_tokens: BondingTokenItem[]; bonding_curve: BondingTokenItem[]; normal: NormalTokenItem[]; } ``` ### `SearchTokenParams` ```typescript export type SearchTokenParams = { keyword?: string; tokenContract?: string; }; ``` ## Troubleshooting If you encounter any issues while using the StxCity SDK, please check the following: 1. Make sure you have the latest version of the SDK installed. 2. Check that you're using a valid Stacks address for the `senderAddress` parameter. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ```