stxcity-sdk/README.md

SDK for interacting with Stxcity

# 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<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`

```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.

```