# Introduction

Documentation en construction

Avec cette API vous pouvez créer une extension au bot coins pour votre serveur, ou même une extension publique pour tous les serveurs souhaitants l'utiliser et ainsi faire grandir votre propre bot relié au notre !

## A quoi sert cette API ?

Nombreux d'entre vous ont de nouvelles idées pour le bot coins, certains voudraient les commandes en exclusivité pour leur serveur mais nous ne pouvons pas nous le permettre. Cette API va permettre à chaque serveur de créer des extensions au bot coins et ainsi personnaliser l'aventure de ses joueurs !

### Comment l'utiliser ?

Pour cela vous aurez besoin de la clef de votre serveur, pour l'obtenir faites `apikey`sur votre bot, le bot vous enverra la clef d'API, celle-ci sera à mettre comme paramètre apiKey dans vos requêtes!\
 Après il vous suffit de lire la doc et vous inspirer des exemple et des conseils donnés !

### Combien pouvons-nous faire de requêtes ?

Les requêtes sont limités à <mark style="color:red;">20 requêtes par minute</mark> (*sauf pour les* [*prevnames*](/prevnames) *qui eux sont limités à <mark style="color:orange;">5</mark>* <mark style="color:orange;"></mark><mark style="color:orange;">requêtes par minute</mark>*)*


# PrevNames

Requête pour accéder aux prevnames

Afin d'accéder aux anciens pseudos des utilisateurs stockés par nos bots nous vous offrons 6 requêtes par minute afin d'obtenir les prevnames des membres

### Voici la requête

Il suffit de remplacer USER\_ID par l'i de l'utilisateur recherché

```
http://epicbots.xyz/api/prev/read/name?UserId=USER_ID
```

## Module Prevnames

Afin de simplifier l'accès à nos prevnames un module a été mit en place: <https://www.npmjs.com/package/epicbots-prevnames>

```
const EpicBots = require('epicbots-prevnames');

// Définissez l'identifiant du profil à rechercher
let USER_ID = "123456789"

//Effectuez la requête au serveur pour récupérer les prevnames
EpicBots.prevnames(USER_ID)
  .then(data => {
    console.log(data); // Données renvoyées par la méthode prevnames
  })
  .catch(error => {
    // Gérer les erreurs ici
    console.error(error)
  });
```

{% hint style="warning" %}
Il y a une limite de 5 requêtes par minutes, sinon quoi le bot refusera vos requêtes et renverra une erreur 429 !
{% endhint %}


# Remove

Page non rédigée, contactez milleniumishere pour participer à sa rédaction

*Fonction comme les requêtes de type "*[*Add*](/coinsbot/add)*", remplacez "Add" par "Remove"*


# Add


# Définir un solde

Fixe un solde à une valeur exacte (au lieu d'ajouter/retirer). Renvoie la valeur définie.

`GET` `/api/coinsbot/set/{type}`

***

### 🏷️ Types disponibles (`{type}`)

`coins` · `reputation` · `entrepot` · `drugs` · `bank` · `victoires`

***

### 🔧 Paramètres

| Paramètre | Requis | Description                     |
| --------- | :----: | ------------------------------- |
| `GuildId` |    ✅   | ID du serveur                   |
| `UserId`  |    ✅   | ID de l'utilisateur             |
| `apiKey`  |    ✅   | Clé API du serveur              |
| `value`   |    ✅   | Nouvelle valeur exacte (entier) |

***

### 💡 Exemple

**Mettre la banque à 10 000 :**

```http
GET /api/coinsbot/set/bank?GuildId=123&UserId=456&apiKey=CLE&value=10000
```

***

### ✅ Réponse `200`

```json
{ "UserId": "456", "GuildId": "123", "Bank": 10000 }
```

{% hint style="info" %}
Si l'utilisateur n'existe pas encore, il est créé automatiquement avant l'écriture.
{% endhint %}

***

### ❌ Erreurs

|  Code | Cause                       |
| :---: | --------------------------- |
| `400` | Paramètre manquant/invalide |
| `401` | Clé API invalide            |
| `500` | Erreur interne              |


# Drugs

Requête pour ajouter des drugs

### Ajouter des drugs à un utilisateur

Pour ajouter des drugs à un utilisateur du serveur en particulier il faudra utiliser la requête `api/add/drugs`et préciser les champs GuildId, UserId, amountToAdd ainsi que [apiKey](/#comment-lutiliser) .

#### Exemple d'une requête&#x20;

<pre><code><strong>http://epicbots.xyz/api/coinsbot/add/drugs?UserId=USER_ID&#x26;amountToAdd=AMOUNT_TO_ADD&#x26;GuildId=GUILD_ID&#x26;apiKey=API_KEY
</strong></code></pre>


# Victoires

Requête pour ajouter des victoires, si vous faites une extension avec des duels

### Ajouter des victoires à un utilisateur

Pour ajouter des victoires à un utilisateur du serveur en particulier il faudra utiliser la requête `api/add/victoires`et préciser les champs GuildId, UserId, amountToAdd ainsi que [apiKey](/#comment-lutiliser) .

#### Exemple d'une requête&#x20;

<pre><code><strong>http://epicbots.xyz/api/coinsbot/add/victoires?UserId=USER_ID&#x26;amountToAdd=AMOUNT_TO_ADD&#x26;GuildId=GUILD_ID&#x26;apiKey=API_KEY
</strong></code></pre>


# Banque

Requête pour ajouter des coins en banque

### Ajouter des coins en banque à un utilisateur

Pour ajouter des coins à un utilisateur du serveur en particulier il faudra utiliser la requête `api/add/bank`et préciser les champs GuildId, UserId, amountToAdd ainsi que [apiKey](/#comment-lutiliser) .

#### Exemple d'une requête&#x20;

<pre><code><strong>http://epicbots.xyz/api/coinsbot/add/bank?UserId=USER_ID&#x26;amountToAdd=AMOUNT_TO_ADD&#x26;GuildId=GUILD_ID&#x26;apiKey=API_KEY
</strong></code></pre>


# Entrepôt

Requête pour ajouter des coins en entrepot

### Ajouter des coins en entrepôt à un utilisateur

Pour ajouter des coins en entrepôtà un utilisateur du serveur en particulier il faudra utiliser la requête `api/add/entrepot`et préciser les champs GuildId, UserId, amountToAdd ainsi que [apiKey](/#comment-lutiliser) .&#x20;

#### Exemple d'une requête

<pre><code><strong>http://epicbots.xyz/api/coinsbot/add/entrepot?UserId=USER_ID&#x26;amountToAdd=AMOUNT_TO_ADD&#x26;GuildId=GUILD_ID&#x26;apiKey=API_KEY
</strong></code></pre>


# Reputation

Requête pour ajouter des points de réputation

### Ajouter des rep à un utilisateur

Pour ajouter des rep à un utilisateur du serveur en particulier il faudra utiliser la requête `api/add/rep`et préciser les champs GuildId, UserId, amountToAdd ainsi que [apiKey](/#comment-lutiliser) .

#### Exemple d'une requête

<pre><code><strong>http://epicbots.xyz/api/coinsbot/add/reputation?UserId=USER_ID&#x26;amountToAdd=AMOUNT_TO_ADD&#x26;GuildId=GUILD_ID&#x26;apiKey=API_KEY
</strong></code></pre>


# Coins

Requête pour ajouter des coins à un utilisateur

### Ajouter des coins à un utilisateur

Pour ajouter des coins à un utilisateur du serveur en particulier il faudra utiliser la requête `api/add/coins`et préciser les champs GuildId, UserId, amountToAdd ainsi que [apiKey](/#comment-lutiliser) .

#### Exemple d'une requête&#x20;

<pre><code><strong>http://epicbots.xyz/api/coinsbot/add/coins?UserId=USER_ID&#x26;amountToAdd=AMOUNT_TO_ADD&#x26;GuildId=GUILD_ID&#x26;apiKey=API_KEY
</strong></code></pre>


# Users

Dans cette catégorie nous verrons comment récupérer les données des utilisateurs

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><a href="/coinsbot/users/recuperer-un-utilisateur">Récupérer un utilisateur d'un serveur</a></td><td></td><td></td></tr><tr><td><a href="/coinsbot/users/recuperer-tous-les-utilisateurs-dun-serveur">Récupérer tous les utilisateurs d'un serveur</a></td><td></td><td></td></tr></tbody></table>


# Transférer un solde

Transfère un montant d'un joueur vers un autre.

{% hint style="warning" %}
Le débit **ne s'effectue pas** si l'émetteur n'a pas assez de solde : l'opération est refusée (`400`) avant tout crédit du destinataire.
{% endhint %}

`GET` `/api/coinsbot/transfer/{type}`

***

### 🏷️ Types disponibles (`{type}`)

`coins` · `bank` · `entrepot` · `drugs` · `victoires`

***

### 🔧 Paramètres

| Paramètre    | Requis | Description                          |
| ------------ | :----: | ------------------------------------ |
| `GuildId`    |    ✅   | ID du serveur                        |
| `apiKey`     |    ✅   | Clé API du serveur                   |
| `fromUserId` |    ✅   | Émetteur (débité)                    |
| `toUserId`   |    ✅   | Destinataire (crédité)               |
| `amount`     |    ✅   | Montant (entier strictement positif) |

***

### 💡 Exemple

```http
GET /api/coinsbot/transfer/coins?GuildId=123&apiKey=CLE&fromUserId=111&toUserId=222&amount=500
```

***

### ✅ Réponse `200`

```json
{
  "GuildId": "123",
  "column": "Coins",
  "amount": 500,
  "from": "111",
  "to": "222",
  "toBalance": 1200
}
```

| Champ       | Description                                |
| ----------- | ------------------------------------------ |
| `toBalance` | Nouveau solde du destinataire après crédit |

***

### ❌ Erreurs

|  Code | Cause                                                                                     |
| :---: | ----------------------------------------------------------------------------------------- |
| `400` | Paramètre manquant/invalide, `amount` ≤ 0, émetteur = destinataire, **solde insuffisant** |
| `401` | Clé API invalide                                                                          |
| `500` | Erreur interne                                                                            |


# Récupérer un utilisateur

Pour récupérer un utilisateur au sein d'un serveur

`GET` `/api/coinsbot/users/one`

***

### 🔧 Paramètres

| Paramètre | Requis | Description                 |
| --------- | :----: | --------------------------- |
| `GuildId` |    ✅   | ID du serveur               |
| `UserId`  |    ✅   | ID de l'utilisateur Discord |
| `apiKey`  |    ✅   | Clé API du serveur          |

***

### 💡 Exemple

```http
GET /api/coinsbot/users/one?GuildId=123&UserId=456&apiKey=CLE
```

***

### ✅ Réponse `200`

```json
{
  "UserId": "456",
  "GuildId": "123",
  "Coins": 1500,
  "Bank": 8000,
  "Rep": 12,
  "Victoires": 4
}
```

***

### ❌ Erreurs

|  Code | Cause                          |
| :---: | ------------------------------ |
| `400` | `GuildId` ou `UserId` manquant |
| `401` | Clé API invalide               |
| `404` | Utilisateur non trouvé         |
| `500` | Erreur interne                 |


# Récupérer tous les utilisateurs d'un serveur

Récupère les utilisateurs d'un serveur, avec tri et pagination optionnels.

{% hint style="info" %}
Par défaut (**sans `limit`**), **tous** les utilisateurs sont renvoyés.
{% endhint %}

`GET` `/api/coinsbot/users/all`

***

### 🔧 Paramètres

| Paramètre | Requis |   Défaut   | Description                                                    |
| --------- | :----: | :--------: | -------------------------------------------------------------- |
| `GuildId` |    ✅   |      —     | ID du serveur                                                  |
| `apiKey`  |    ✅   |      —     | Clé API du serveur                                             |
| `limit`   |    ❌   | *(aucune)* | Nombre max de résultats. Absent = tout renvoyer. Max `100000`. |
| `offset`  |    ❌   |     `0`    | Décalage pour la pagination                                    |
| `sortBy`  |    ❌   |  *(aucun)* | Colonne de tri — voir ci-dessous                               |
| `order`   |    ❌   |    `asc`   | `asc` (croissant) ou `desc` (décroissant)                      |

#### 🔀 Valeurs de `sortBy`

`coins` · `bank` · `total` *(= coins + banque)* · `rep` · `livret` · `drugs` · `crypto` · `entrepot` · `xp` · `level` · `victoires` · `masterbalance` · `combowin` · `combolose`

{% hint style="info" %}
Le tri est **numérique**, même pour les colonnes stockées en texte en base.
{% endhint %}

***

### 💡 Exemples

**Tout le monde, trié par coins en main croissant :**

```http
GET /api/coinsbot/users/all?GuildId=123&apiKey=CLE&sortBy=coins&order=asc
```

**Les 25 plus riches (coins + banque), paginé :**

```http
GET /api/coinsbot/users/all?GuildId=123&apiKey=CLE&sortBy=total&order=desc&limit=25&offset=0
```

***

### ✅ Réponse `200`

Tableau d'objets utilisateur :

```json
[
  { "UserId": "111", "GuildId": "123", "Coins": 50, "Bank": 200, "Rep": 3 },
  { "UserId": "222", "GuildId": "123", "Coins": 120, "Bank": 0, "Rep": 1 }
]
```

***

### ❌ Erreurs

|  Code | Cause                                                          |
| :---: | -------------------------------------------------------------- |
| `400` | `GuildId` manquant, `sortBy`/`order`/`limit`/`offset` invalide |
| `401` | Clé API invalide                                               |
| `500` | Erreur interne                                                 |


# Classement

Renvoie le classement d'un serveur, avec le rang déjà calculé.

{% hint style="info" %}
Résultat mis en cache **30 secondes**.
{% endhint %}

`GET` `/api/coinsbot/users/top`

***

### 🔧 Paramètres

| Paramètre | Requis |  Défaut | Description                             |
| --------- | :----: | :-----: | --------------------------------------- |
| `GuildId` |    ✅   |    —    | ID du serveur                           |
| `apiKey`  |    ✅   |    —    | Clé API du serveur                      |
| `sortBy`  |    ❌   | `total` | Critère de classement — voir /users/all |
| `order`   |    ❌   |  `desc` | `desc` (défaut) ou `asc`                |
| `limit`   |    ❌   |   `10`  | Nombre de joueurs (max `100`)           |

***

### 💡 Exemple

**Top 5 par coins en banque :**

```http
GET /api/coinsbot/users/top?GuildId=123&apiKey=CLE&sortBy=bank&limit=5
```

***

### ✅ Réponse `200`

```json
{
  "GuildId": "123",
  "sortBy": "bank",
  "order": "desc",
  "count": 5,
  "top": [
    { "rank": 1, "UserId": "111", "Coins": 50, "Bank": 99000, "Total": 99050 },
    { "rank": 2, "UserId": "222", "Coins": 10, "Bank": 42000, "Total": 42010 }
  ]
}
```

***

### ❌ Erreurs

|  Code | Cause                                         |
| :---: | --------------------------------------------- |
| `400` | `GuildId` manquant, `sortBy`/`order` invalide |
| `401` | Clé API invalide                              |
| `500` | Erreur interne                                |


# Rang d'un joueur

Renvoie la position d'un joueur dans le classement de son serveur, selon n'importe quel critère triable.

`GET` `/api/coinsbot/users/rank`

***

### 🔧 Paramètres

| Paramètre | Requis |  Défaut | Description               |
| --------- | :----: | :-----: | ------------------------- |
| `GuildId` |    ✅   |    —    | ID du serveur             |
| `UserId`  |    ✅   |    —    | ID de l'utilisateur       |
| `apiKey`  |    ✅   |    —    | Clé API du serveur        |
| `sortBy`  |    ❌   | `total` | Critère — voir /users/all |

***

### 💡 Exemple

```http
GET /api/coinsbot/users/rank?GuildId=123&UserId=456&apiKey=CLE&sortBy=total
```

***

### ✅ Réponse `200`

```json
{
  "GuildId": "123",
  "UserId": "456",
  "sortBy": "total",
  "value": 9500,
  "rank": 3,
  "total": 128
}
```

| Champ   | Description                             |
| ------- | --------------------------------------- |
| `value` | Valeur du joueur pour le critère choisi |
| `rank`  | Sa position (`1` = premier)             |
| `total` | Nombre total de joueurs dans le serveur |

***

### ❌ Erreurs

|  Code | Cause                                             |
| :---: | ------------------------------------------------- |
| `400` | `GuildId` ou `UserId` manquant, `sortBy` invalide |
| `401` | Clé API invalide                                  |
| `404` | Utilisateur non trouvé                            |
| `500` | Erreur interne                                    |


# Utilitaire

Ici vous pouvez consulter les requêtes pour obtenir des données complémentaires du bot


# Statistiques d'un serveur

Renvoie des statistiques économiques agrégées pour un serveur (richesse totale, moyenne, maximum…).

{% hint style="info" %}
Résultat mis en cache **30 secondes**.
{% endhint %}

`GET` `/api/coinsbot/users/stats`

***

### 🔧 Paramètres

| Paramètre | Requis | Description        |
| --------- | :----: | ------------------ |
| `GuildId` |    ✅   | ID du serveur      |
| `apiKey`  |    ✅   | Clé API du serveur |

***

### 💡 Exemple

```http
GET /api/coinsbot/users/stats?GuildId=123&apiKey=CLE
```

***

### ✅ Réponse `200`

```json
{
  "GuildId": "123",
  "players": 128,
  "totalCoins": 1500000,
  "totalBank": 8200000,
  "totalWealth": 9700000,
  "avgWealth": 75781.25,
  "maxWealth": 990000
}
```

| Champ         | Description                      |
| ------------- | -------------------------------- |
| `players`     | Nombre de joueurs                |
| `totalCoins`  | Somme des coins en main          |
| `totalBank`   | Somme des coins en banque        |
| `totalWealth` | Richesse totale (main + banque)  |
| `avgWealth`   | Richesse moyenne par joueur      |
| `maxWealth`   | Richesse du joueur le plus riche |

***

### ❌ Erreurs

|  Code | Cause              |
| :---: | ------------------ |
| `400` | `GuildId` manquant |
| `401` | Clé API invalide   |
| `500` | Erreur interne     |


# Nombre d'utilisateurs

Renvoie le nombre d'utilisateurs enregistrés dans un serveur.

`GET` `/api/coinsbot/users/count`

***

### 🔧 Paramètres

| Paramètre | Requis | Description        |
| --------- | :----: | ------------------ |
| `GuildId` |    ✅   | ID du serveur      |
| `apiKey`  |    ✅   | Clé API du serveur |

***

### 💡 Exemple

```http
GET /api/coinsbot/users/count?GuildId=123&apiKey=CLE
```

***

### ✅ Réponse `200`

```json
{ "GuildId": "123", "count": 128 }
```

***

### ❌ Erreurs

|  Code | Cause              |
| :---: | ------------------ |
| `400` | `GuildId` manquant |
| `401` | Clé API invalide   |
| `500` | Erreur interne     |


# Volume de commandes

Renvoie le volume de commandes exécutées sur une période donnée, avec les tops serveurs et utilisateurs.

{% hint style="success" %}
Route **publique** — aucune clé API requise.
{% endhint %}

{% hint style="info" %}
Mise en cache **60 secondes** par période.
{% endhint %}

`GET` `/api/coinsbot/users/commandssize`

***

### 🔧 Paramètres

| Paramètre | Requis | Défaut | Description                |
| --------- | :----: | :----: | -------------------------- |
| `hours`   |    ❌   |  `24`  | Fenêtre de temps en heures |

***

### 💡 Exemple

**Sur les 7 derniers jours :**

```http
GET /api/coinsbot/users/commandssize?hours=168
```

***

### ✅ Réponse `200`

```json
{
  "timeRange": 24,
  "totalCommands": 128000,
  "topGuilds": [
    { "guildId": "123", "totalCommands": 4200 }
  ],
  "topUsers": [
    { "userId": "456", "totalCommands": 890 }
  ]
}
```

***

### ❌ Erreurs

|  Code | Cause          |
| :---: | -------------- |
| `500` | Erreur interne |