Skip to main content
For the complete documentation index, see llms.txt. 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.
Generate your API key at users.shakesco.com/user/api-tokens
Never embed your API key in browser or mobile-client code. The Tokens API is designed for server-to-server calls only.

​
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

  • 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

​
Endpoint Groups

Rewards

Claim, redeem, expire tokens and award pending rewards

Transfer

Transfer tokens between users or migrate from another system

Staking

Lock tokens into stakes and collect staking rewards

Vesting

Create, claim, and cancel vesting grants

Promotions

Run happy hours and set daily earning caps

Governance & Cashback

Configure tiers, voting ratios, and cashback programs

Read & Query

Check balances, user info, and activity

Events

Manage token claim events used by /claim-tokens

​
Common Error Codes