# Referral Scheme

## Getting Referral Earnings

{% hint style="success" %}
Remember you can always earn referral commissions without using the API.

Just share your referral link <https://ordinalsbot.com/?ref=your-referral-code> with your community, visitors or followers and you'll automatically earn referral commissions from the inscriptions they make.
{% endhint %}

Use this endpoint to check earnings for your referrals code:

## Get Referral Status

<mark style="color:blue;">`GET`</mark> `https://api.ordinalsbot.com/referrals`

Check referral earning status.

Your referral earning is calculated as

`paidCount * baseFee * 0.15`

`(e.g. 100 * 9000 (sats) * %15 commission)`

#### Query Parameters

| Name                                       | Type   | Description                                      |
| ------------------------------------------ | ------ | ------------------------------------------------ |
| referral<mark style="color:red;">\*</mark> | String | Your referral code                               |
| address<mark style="color:red;">\*</mark>  | String | Your bitcoin address that you've set for payouts |

{% tabs %}
{% tab title="200: OK Normal Response" %}

```
{
    "address":"bc1qxxx",
    "orderCount":962, // how many orders were created with your reflink
    "paidCount":305 // how many paid orders were processed.
}
```

{% endtab %}

{% tab title="200: OK Error Response with Cause" %}

```
{
    status: 'error', 
    error: 'error reason'
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server side error" %}

```
{
    status: 'error',
    reason: 'unable to check data'
}
```

{% endtab %}
{% endtabs %}

## Saving Referral Code

Use this endpoint to set a unique referral code for yourself.

## Set referral code and payout address

<mark style="color:green;">`POST`</mark> `https://api.ordinalsbot.com/referrals`

Use this endpoint to set your referral code and payout address. Your address allows you to query your referral earnings.

#### Request Body

| Name                                       | Type   | Description                                               |
| ------------------------------------------ | ------ | --------------------------------------------------------- |
| referral<mark style="color:red;">\*</mark> | String | Your unique referral code                                 |
| address<mark style="color:red;">\*</mark>  | String | Your bitcoin address that you want to receive payouts to. |

{% tabs %}
{% tab title="200: OK Normal Response" %}

```
{
    "status":"ok" // your information is saved.
}
```

{% endtab %}

{% tab title="200: OK Error Response with Cause" %}

```
{
    status: 'error', 
    error: 'referral code already exists - pick another one'
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server side error" %}

```
{
    status: 'error',
    reason: 'unable to set data'
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Get in touch for any questions regarding referral setup in our discord: [https://discord.ordinalsbot.com](https://discord.ordinalsbot.com/)
{% endhint %}