> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shakesco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens API Overview

> Manage loyalty tokens for your customers via tokens.shakesco.com

<span style={{display:"none"}}>For the complete documentation index, see [llms.txt](/llms.txt).</span>

The Tokens API (`https://tokens.shakesco.com`) lets your backend award, transfer, redeem, stake, and vest loyalty tokens for your customers. You hand Shakesco a customer identifier and a token amount; we take care of everything else.

## Authentication

All requests require your API key in the `Authorization` header. The API resolves your key to your business token contract automatically.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Note>
  Generate your API key at [users.shakesco.com/user/api-tokens](https://users.shakesco.com/user/api-tokens)
</Note>

<Warning>
  Never embed your API key in browser or mobile-client code. The Tokens API is designed for server-to-server calls only.
</Warning>

## Identifying Customers

Every endpoint that targets a specific customer takes a `customer_ref` field. This is any string that uniquely identifies that customer **inside your business**: a UUID, account number, phone number, email, or anything else you already store.

Two rules:

1. **Use the same value every time for the same customer.** If you send `user-7421` once and `7421` later, those become two different customers as far as the API is concerned.
2. **The value only needs to be unique inside your business**, not globally.

In the examples throughout these docs we use short opaque strings like `customer-123`. In practice we recommend whatever stable internal ID you already have, usually your primary key. Email works, but if a customer ever changes their email you will lose access to their balance.

## How It Works

```
Your backend → POST tokens.shakesco.com/claim-tokens → Tokens credited to customer
```

* Customers are identified by a `customer_ref` string you choose.
* Write endpoints return a `tx_hash` once the change is recorded. You don't need to do anything with this value, it's just an audit trail.
* Read endpoints return token amounts as plain decimal strings (for example `"50"`, not raw integers).
* Percentages are plain numbers (`20` means 20%). Time fields are in seconds.

## Treat Writes as Transactions

Every `POST` endpoint mutates state and should be treated like a payment transaction in your own system:

* **Don't fire-and-forget.** Wait for the `200 OK` response before telling the customer the action succeeded. The call is synchronous: the response arrives only once the change is fully recorded.
* **Be idempotent on your side.** If your request times out or you don't get a response, query the read endpoints (`/balance`, `/has-claimed-event`, etc.) to check whether the change applied before retrying. Blindly retrying can double-credit a customer.
* **Store the `tx_hash`.** It's your audit trail if you ever need to reconcile state with Shakesco.
* **Handle the error codes.** A `429 Daily earning cap exceeded` or `409 Event already claimed` is a normal outcome you should surface in your own UI, not an exception to swallow.

## Base URL

```
https://tokens.shakesco.com
```

## Endpoint Groups

<CardGroup cols={2}>
  <Card title="Rewards" icon="gift" href="/api-reference/tokens/rewards/claim-tokens">
    Claim, redeem, expire tokens and award pending rewards
  </Card>

  <Card title="Transfer" icon="arrow-right-arrow-left" href="/api-reference/tokens/transfer/transfer-tokens">
    Transfer tokens between users or migrate from another system
  </Card>

  <Card title="Staking" icon="coins" href="/api-reference/tokens/staking/set-staking-rate">
    Lock tokens into stakes and collect staking rewards
  </Card>

  <Card title="Vesting" icon="clock" href="/api-reference/tokens/vesting/create-vesting-grant">
    Create, claim, and cancel vesting grants
  </Card>

  <Card title="Promotions" icon="champagne-glasses" href="/api-reference/tokens/promotions/set-happy-hour">
    Run happy hours and set daily earning caps
  </Card>

  <Card title="Governance & Cashback" icon="layer-group" href="/api-reference/tokens/governance/set-tiers">
    Configure tiers, voting ratios, and cashback programs
  </Card>

  <Card title="Read & Query" icon="magnifying-glass" href="/api-reference/tokens/read/balance">
    Check balances, user info, and activity
  </Card>

  <Card title="Events" icon="calendar" href="/api-reference/tokens/events/set-event-details">
    Manage token claim events used by `/claim-tokens`
  </Card>
</CardGroup>

## Common Error Codes

| Code | Error                        | Meaning                                     |
| ---- | ---------------------------- | ------------------------------------------- |
| 400  | `Invalid parameters`         | Check field types and values                |
| 400  | `Insufficient token balance` | Customer does not have enough tokens        |
| 400  | `No tokens are claimable`    | Vesting schedule has nothing to claim yet   |
| 401  | `Unauthorized`               | Missing or invalid API key                  |
| 403  | `Caller not authorized`      | Your API key is not linked to this token    |
| 404  | `Event not found`            | Event name is not configured for your token |
| 409  | `Event already claimed`      | Customer already claimed a one-time event   |
| 409  | `Stake already unlocked`     | Cannot unstake an already-unlocked position |
| 429  | `Daily earning cap exceeded` | Customer hit the daily token earning limit  |
| 429  | `Fee limit exceeded`         | Your API compute budget is exhausted        |
| 502  | `Transaction failed`         | Operation could not be completed, retry     |