# API

### 🌐 Base URL

All requests are made to:

```agda
https://webapi.raybot.app
```

***

## 🔐 Authentication

### Getting an API Key

You can obtain an API key directly in the RayBot Telegram Bot by sending the command:

```
/api
```

<details>

<summary>📍Example</summary>

<figure><img src="https://1876630604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCbb55jaA7AAtvB0Mx70g%2Fuploads%2FvbiVUD10jqQV0yKlN1jv%2FApi2.gif?alt=media&#x26;token=f1dc2732-92d6-4f96-aba9-116a837058ff" alt=""><figcaption></figcaption></figure>

</details>

***

### Required Parameters

> All requests to **`/publicapi`** must include two parameters:
>
> * `api_user`: — Your API user id
> * `token`: — Your API key

***

### Data Format

Parameters can be passed in the query string.

```atom
GET /publicapi/wallets?api_user=your_user_id&token=your_api_key
```

***

### Rate Limits

**Public API endpoints (**`/publicapi`**)**: — 5 requests per 10 seconds

***

### Bot numbers <a href="#bot-numbers" id="bot-numbers"></a>

With each request, you need to specify a Telegram bot number. Use the table below to find the correct bot:

<details>

<summary>Ray Bots:</summary>

```
0: @solana_notify_bot
1: @ray_purple_bot
2: @ray_red_bot
3: @ray_blue_bot
4: @ray_gold_bot
5: @ray_silver_bot
6: @ray_black_bot
7: @ray_ruby_bot
8: @ray_sapphire_bot
9: @ray_pearl_bot
10: @ray_green_bot
11: @ray_yellow_bot
12: @ray_opal_bot
13: @ray_diamond_bot
14: @ray_emerald_bot
15: @ray_topaz_bot
16: @ray_cyan_bot
17: @ray_orange_bot
18: @ray_adamite_bot
19: @ray_amber_bot
20: @ray_onyx_bot
21: @ray_quartz_bot
22: @ray_obsidian_bot
23: @ray_nephrite_bot
24: @ray_moonstone_bot
25: @ray_agate_bot
26: @ray_azure_bot
27: @ray_magenta_bot
28: @ray_lime_bot
29: @ray_olive_bot
30: @ray_aqua_bot
31: @ray_bronze_bot
32: @ray_violet_bot
33: @ray_khaki_bot
```

</details>

***

## 📋 Endpoints

### **Add Wallets**

**Endpoint:**  `POST /publicapi/wallets/add`

Add multiple wallets to a user's bot configuration.

#### **Parameters:**

> **Query Parameters:**
>
> * `api_user` (string, required): Your API user ID
> * `token` (string, required): API authentication token

**Request Body:**

```json
{
  "user_id": "string",
  "bot": 1,
  "wallets": [
    {
      "wallet_address": "string",
      "wallet_name": "string (optional)"
    },
    {
      "wallet_address": "string",
      "wallet_name": "string (optional)"
    },
    ...
  ]
}
```

> **Validation Rules:**
>
> * Maximum 10 wallets per request
> * `wallet_address` must be alphanumeric
> * `bot` must be integer between 0-32
> * `wallets` array must contain 1-10 items

**Response:**

```json
{
  "status": "ok" | "error",
  "wallets": [
    {
      "address": "string",
      "type": "solana" | "evm",
      "status": "active" | "limit" | "user_pause",
      "wallet_name": "string",
      "bot": 1
    }
  ]
}
```

> **Status Codes**
>
> * `201`: Wallets added successfully
> * `400`: Invalid request data
> * `401`: Invalid authentication
> * `403`: User not authorized
> * `429`: Rate limit exceeded

***

### **Delete Wallets**

**Endpoint:** `POST /publicapi/wallets/delete`

**Parameters:**

> **Query Parameters:**
>
> * `api_user` (string, required): Your API user ID
> * `token` (string, required): API authentication token

**Request Body:**

```json
{
  "wallets": ["wallet_address_1", "wallet_address_2"],
  "user_id": "string",
  "bot": 1
}
```

> **Validation Rules:**
>
> * `wallets` must be a non-empty array
> * Each wallet address must be valid Solana, EVM, or TRON address
> * `bot` must be integer between 0-32

**Response:**

```json
{
  "status": "ok",
  "deletedCount": 2
}
```

> **Status Codes:**
>
> * `200`: Wallets deleted successfully
> * `400`: Invalid wallet addresses
> * `401`: Invalid authentication
> * `404`: No wallets found
> * `429`: Rate limit exceeded

***

### **Get Wallets (paginated)**

**Endpoint:**  `POST /publicapi/wallets/show`

Retrieve all wallets for the authenticated user, with optional filtering and pagination.

**Parameters:**

> **Query Parameters:**
>
> * `api_user` (string, required): Your API user ID
> * `token` (string, required): API authentication token

**Request Body:**

```json
{
  "page": 1,
  "limit": 50,
  "bot": 1,
  "user_id": "string"
}
```

> **Validation Rules:**
>
> * `page` must be an integer (default: 1, min: 1)
> * `limit` (page size) must be an integer (default: 50, min: 1, max: 200)
> * `bot` must be integer between 0-32

**Response:**

```json
{
  "status": "ok",
  "wallets": [
    {
      "address": "string",
      "type": "solana" | "evm",
      "status": "active" | "user_pause" | "limit",
      "wallet_name": "string",
      "bot": 1,
      "user_id": "string"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 123,
  "totalPages": 3,
  "nextPage": 2,
  "prevPage": null
}
```

> **Status Codes:**
>
> * `200`: Success
> * `401`: Invalid authentication
> * `429`: Rate limit exceeded
> * `400`: Validation error (missing/invalid params)

***

### **Update Wallet Settings**

**Endpoint:**  `POST /publicapi/wallets/settings`

Update tx filter settings for a specific wallet that belongs to the authenticated admin (API user).

**Parameters:**

> **Query Parameters:**
>
> * `api_user` (string, required): Your API user ID
> * `token` (string, required): API authentication token

**Request Body:**

```json
{
  "bot": 1,
  "user_id": "string",
  "wallet_address": "string",
  "settings": {
    "[boolean_key]": true | false,
    "[numeric_key": 123.456 
  }
}
```

> **Validation Rules:**
>
> * `bot` must be integer between 0-32
> * `wallet_address` must be a valid Solana / EVM / Tron address
> * `settings` must be an object

**Supported `settings` Keys**

<details>

<summary>Boolean Settings</summary>

Solana:

* `nfts`, `swaps`, `buys`, `sells`, `first_buy_only`, `first_sell_only`, `new_transfers_only`, `transfers`, `in_txs`, `out_txs`, `other`, `token_transfers`, `in_low_lq_transfers`, `likely_scam_transfers`, `multi_transfers`, `multi_transfers_ex`, `burn`, `drip`, `cnfts`, `jup_dca`, `jup_limit`, `jupiter`, `jupiter_perps`, `meteora`, `jito_tip`, `pumpfun`, `pumpswap`, `raydium`, `unknown`, `approvals`, `associated_token`, `close_token_account`, `add_liquidity`, `remove_liquidity`, `claim_fees`, `spam`, `token_mint`, `migrate`, `streamflow`

EVM:

* `evm_swaps`, `evm_buys`, `evm_sells`, `evm_transfers`, `evm_other`, `evm_tip`

TRON:

* `tron_swaps`, `tron_buys`, `tron_sells`, `tron_transfers`, `tron_other`, `tron_tip`

</details>

<details>

<summary>Numeric Settings</summary>

Solana:

* `min_sol`, `max_sol`, `min_usd`, `max_usd`, `min_trade_sol`, `max_trade_sol`, `min_trade_usd_mc`, `max_trade_usd_mc`, `min_token_age`, `max_token_age`

EVM:

* `evm_trade_min`, `evm_trade_max`, `evm_mc_trade_min`, `evm_mc_trade_max`, `evm_usd_min`, `evm_usd_max`

TRON:

* `tron_trade_min`, `tron_trade_max`, `tron_mc_trade_min`, `tron_mc_trade_max`, `tron_usd_min`, `tron_usd_max`

</details>

**Response:**

```json
{
  "status": "ok",
  "wallet": {
    "address": "string",
    "type": "solana" | "evm",
    "status": "active" | "user_pause" | "limit",
    "wallet_name": "string",
    "bot": 1,
    "user_id": "string",
    "tx_filter": { // Full post-update filter map for this wallet
      "...": "[current settings after update]"
    }
  },
  "updated": 5 // Number of individual fields changed in this request
}
```

> **Status Codes:**
>
> * `200`: Success
> * `400`: Validation error (missing/invalid params)
> * `401`: Invalid authentication
> * `429`: Rate limit exceeded

***

## 🔧 SDKs and Examples <a href="#sdks-and-examples" id="sdks-and-examples"></a>

### **JavaScript/Node.js Example**

```javascript
const axios = require('axios');

const apiClient = axios.create({
  baseURL: 'https://webapi.raybot.app',
  timeout: 30000,
});

// Add wallets
async function addWallets(userId, token, wallets, bot = 1) {
  try {
    const response = await apiClient.post(
      `/publicapi/wallets/add?api_user=${userId}&token=${token}`,
      {
        user_id: userId,
        bot: bot,
        wallets: wallets
      }
    );
    return response.data;
  } catch (error) {
    console.error('Error adding wallets:', error.response?.data || error.message);
    throw error;
  }
}

// Usage examples
const wallets = [
  { wallet_address: 'ABC123...', wallet_name: 'My Wallet 1' },
  { wallet_address: 'DEF456...', wallet_name: 'My Wallet 2' }
];

addWallets('api_user_id', 'your_api_token', wallets)
  .then(result => console.log('Wallets added:', result))
  .catch(error => console.error('Failed to add wallets:', error));
```

### **Python Example**

```python
import requests
import json

class RayBotAPI:
    def __init__(self, base_url, user_id, token):
        self.base_url = base_url
        self.user_id = user_id
        self.token = token
        
    def add_wallets(self, wallets, bot=1):
        url = f"{self.base_url}/publicapi/wallets/add"
        params = {"api_user": self.user_id, "token": self.token}
        data = {
            "user_id": self.user_id,
            "bot": bot,
            "wallets": wallets
        }
        
        response = requests.post(url, params=params, json=data)
        response.raise_for_status()
        return response.json()

# Usage
api = RayBotAPI("https://webapi.raybot.app", "api_user_id", "your_token")

wallets = [
    {"wallet_address": "ABC123...", "wallet_name": "My Wallet 1"}
]

try:
    result = api.add_wallets(wallets)
    print(f"Added {len(result['wallets'])} wallets")
except requests.exceptions.HTTPError as e:
    print(f"Error: {e.response.json()}")
```