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 theAuthorization header. The API resolves your key to your business token contract automatically.
Generate your API key at users.shakesco.com/user/api-tokens
Identifying Customers
Every endpoint that targets a specific customer takes acustomer_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:
- Use the same value every time for the same customer. If you send
user-7421once and7421later, those become two different customers as far as the API is concerned. - The value only needs to be unique inside your business, not globally.
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_refstring you choose. - Write endpoints return a
tx_hashonce 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 (
20means 20%). Time fields are in seconds.
Treat Writes as Transactions
EveryPOST endpoint mutates state and should be treated like a payment transaction in your own system:
- Don’t fire-and-forget. Wait for the
200 OKresponse 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 exceededor409 Event already claimedis 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-tokensCommon 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 |