# Affiliate

### 1. Overview

The Coinlocally Affiliate API allows affiliates to retrieve referral information for their referred users.

To use the API, each affiliate must first obtain an **API Key** and **Secret Key**. These credentials are used to authenticate all requests by generating a secure **HMAC SHA256 signature**.

### 2. Authentication

#### Required Headers

Every request must include the following headers:

| Header        | Description                                  |
| ------------- | -------------------------------------------- |
| `x-api-key`   | Affiliate’s API key                          |
| `x-signature` | HMAC SHA256 signature of payload + timestamp |
| `x-timestamp` | Current timestamp in milliseconds            |

#### Signature Generation

```js
signature = HmacSHA256(payload, secretKey).toString(crypto.enc.Hex)
```

Where:

* **payload** = `JSON.stringify(requestBody) + timestamp`
* **secretKey** = Your affiliate secret key

### 3. API Endpoint

**URL**:

```
https://official.coinlocally.com/v1/affiliates/referredInfo
```

**Method**:

```
POST
```

### 4. Request

#### Body Parameters

| Field    | Type   | Required | Description                      |
| -------- | ------ | -------- | -------------------------------- |
| `userId` | number | ✅        | The unique ID of the user        |
| `email`  | string | ❌        | The email of the user (optional) |

#### Example Request Body

```json
{
  "userId": 12345
}
```

OR (with email):

```json
{
  "userId": 12345,
  "email": "user@example.com"
}
```

### 5. Response

#### Example Response

```json
{
  "error": false,
  "message": null,
  "result": {
    "isDirectReferral": true,
    "totalTradeVolumes": "0.0",
    "totalDeposits": "0.0",
    "SpotBalanceInUsdt": "0.0",
    "futuresBalanceInUsdt": "0.0"
  }
}
```

***

### 6. Postman Pre-Request Script

```js
const apiKey = pm.environment.get("api-key")
const secretKey = pm.environment.get("api-secret")
const timestamp = Date.now().toString();

let body = '';
if (pm.request.body && pm.request.body.raw) {
    body = JSON.parse(pm.request.body.raw);
}
const payload = JSON.stringify(body) + timestamp;

const crypto = require('crypto-js');
const signature = crypto.HmacSHA256(payload, secretKey).toString(crypto.enc.Hex);

pm.request.headers.upsert({ key: 'x-api-key', value: apiKey });
pm.request.headers.upsert({ key: 'x-signature', value: signature });
pm.request.headers.upsert({ key: 'x-timestamp', value: timestamp });
```

***

### 7. Python Implementation Example

```python
import time, json, hmac, hashlib, requests

class CoinlocallyAffiliate:
    def __init__(self, api_key, secret_key, logger_error=print):
        self.api_key = api_key
        self.secret_key = secret_key
        self.logger_error = logger_error

    def get_info_coinlocally(self, uid, email):
        url = 'https://official.coinlocally.com/v1/affiliates/referredInfo'

        # Request body
        body = {
            "userId": uid,
            "email": email,
        }

        # Timestamp
        timestamp = str(int(time.time() * 1000))

        # Payload = body + timestamp
        payload = json.dumps(body, separators=(',', ':')) + timestamp

        # Signature
        signature = hmac.new(
            self.secret_key.encode(),
            payload.encode(),
            hashlib.sha256
        ).hexdigest()

        # Headers
        headers = {
            'x-api-key': self.api_key,
            'x-signature': signature,
            'x-timestamp': timestamp,
            'Content-Type': 'application/json'
        }

        try:
            response = requests.post(url, headers=headers, json=body, verify=False)
            if response.status_code == 201:
                return response.json()
            else:
                return {
                    "error": True,
                    "status_code": response.status_code,
                    "message": response.text
                }
        except Exception as e:
            self.logger_error(f"Error in response API: {e}")
            return {"error": True, "message": str(e)}
```

✅ Now affiliates can securely connect and retrieve referral information using the provided API Key and Secret Key.


---

# 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.coinlocally.com/affiliate.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.