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
2. Configuration
3. Usage
4. Available Functions
5. Public Methods
6. Types
7. Troubleshooting
8. License

Installation

Install the StxCity SDK using npm:

npm install stxcity-sdk

Usage

Here's a step-by-step guide to implement the StxCity SDK in your project:

1. Import the SDK:

import { StxCitySDK } from 'stxcity-sdk';

2. Initialize the SDK:

Option 1: Use a config object

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:

const stxcitySDK = new StxCitySDK(new StacksMainnet())

Available functions

Buy Bonding Token

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

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.

const isValid = await StxCitySDK.checkValidBondingToken('dexContractId', 'tokenContractId');

Get Bonding Token

let page = 1;
let limit = 40
const bondingTokenData = await StxCitySDK.getBondingToken(page, limit);

limit max is 100

Search Token

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<void>

Buys a bonding token with the specified parameters.

sellBondingToken(params: SellBondingTokenParams): Promise<void>

Sells a bonding token with the specified parameters.

getBondingToken(page: number, limit: number): Promise<BondingTokenData>

Fetches bonding token data for the specified page and limit.

searchToken(params?: SearchTokenParams): Promise<SearchTokenType>

Searches for tokens based on the provided parameters.

Types

The following types and interfaces are exported from the types.ts file:

StxCityContext

export interface StxCityContext {
  validAPIKey: boolean;
  network: StacksNetwork;
}

BondingTokenItem

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

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

export interface BondingTokenData {
  trending: BondingTokenItem[];
  new: BondingTokenItem[];
  completed: BondingTokenItem[];
  all: BondingTokenItem[];
  total: number;
  page: number;
  limit: number;
}

BuyBondingTokenParams

export interface BuyBondingTokenParams {
  stxAmount: number;
  dexContractId: string;
  tokenContractId: string;
  tokenSymbol: string;
  senderAddress: string;
  slippage: number;
  stacksProvider?: StacksProvider;
  onFinish?: (data: any) => void;
  onCancel?: () => void;
}

SellBondingTokenParams

export interface SellBondingTokenParams {
  tokenAmount: number;
  dexContractId: string;
  tokenContractId: string;
  tokenSymbol: string;
  senderAddress: string;
  slippage: number;
  stacksProvider?: StacksProvider;
  onFinish?: (data: any) => void;
  onCancel?: () => void;
}

SearchTokenType

export interface SearchTokenType {
  ads_tokens: BondingTokenItem[];
  bonding_curve: BondingTokenItem[];
  normal: NormalTokenItem[];
}

SearchTokenParams

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 file for details.