# 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()}")
```


---

# 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.raybot.app/start/dev/api.md?ask=<question>
```

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.