TISH
v1.0 · Phase 1← Back to home
Developer Reference

TISH API Documentation

Integrate TISH loyalty points into your platform in under 30 minutes. The TISH SDK handles all caps, tiers, treasury routing, and compliance automatically.

Overview

TISH exposes a REST API and an npm SDK (@insiderone/tish). The SDK is the recommended integration method — it wraps all REST calls, enforces daily caps, and handles treasury splits automatically.

Base URL
https://api.tishlabs.com/v1
Auth
Bearer token (API key)
Format
JSON

Phase 1 note: The TISH API is in closed beta. API keys are issued to approved platform partners only. Email tishlabs@insiderone.in to apply.

Quickstart

Get running in 4 steps:

bash
npm install @insiderone/tish
env
# .env
TISH_API_KEY=tk_live_xxxxxxxxxxxxxxxxxxxx
TISH_PLATFORM_ID=plt_xxxxxxxxxxxxxxxxxxxx
typescript
import { tish } from "@insiderone/tish";

// Reward a user action
await tish.earn({
  userId: "usr_abc123",
  action: "content_created",
});

// Gate a premium feature
const result = await tish.spend({
  userId: "usr_abc123",
  amount: 50,
  action: "ai_credit",
});

if (!result.ok) {
  // Insufficient balance — show upgrade prompt
}
typescript
// Get user balance + tier
const user = await tish.getUser({ userId: "usr_abc123" });
console.log(user.balance);    // 1250
console.log(user.tier);       // "Curator"
console.log(user.multiplier); // 2 (Founding Members get 2x)

Authentication

All API requests require a Bearer token in the Authorization header. Never expose your API key client-side.

http
Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx
X-TISH-Platform: plt_xxxxxxxxxxxxxxxxxxxx

Security: API keys must only be used server-side. Exposing a key client-side will result in immediate revocation. Use environment variables. Never commit keys to version control.

Earn TISH

POST
/v1/earn

Award TISH to a user for a completed action. SDK enforces daily caps automatically.

Request body

userId*
string

Your platform's unique user identifier. We store a hash — we never receive PII.

action*
string

One of: content_created, content_imported, collection_imported, referral_registered, streak_7day, custom (requires approval).

amount
number

Override amount in TISH. Must be within ±10% of standard rate. Omit to use platform default.

idempotencyKey
string

Unique key to prevent duplicate rewards. Use your event ID. Recommended for all production calls.

metadata
object

Optional key-value pairs for your own analytics. Not used by TISH.

typescript
await tish.earn({
  userId: "usr_abc123",
  action: "referral_registered",
  idempotencyKey: "evt_signup_usr_xyz789",
});
json
// Response 201
{
  "ok": true,
  "awarded": 25,
  "newBalance": 275,
  "tier": "Builder",
  "multiplier": 2
}

Important: TISH earn must only be triggered by user actions, never by monetary payments. The referral_registered action must fire on signup, not on payment. This is a hard requirement of the TISH Platform Agreement and Constitution.

Spend TISH

POST
/v1/spend

Deduct TISH from a user's balance for a premium feature. SDK routes treasury split automatically.

Request body

userId*
string

Your platform's unique user identifier.

amount*
number

TISH to deduct from user balance.

action*
string

Feature being unlocked. e.g. ai_credit, premium_export, badge_unlock, governance_vote.

idempotencyKey
string

Unique key to prevent double-spending. Use your transaction/session ID.

typescript
const result = await tish.spend({
  userId: "usr_abc123",
  amount: 100,
  action: "ai_credit",
  idempotencyKey: "sess_abc123_ai_1",
});

if (!result.ok) {
  // result.error === "INSUFFICIENT_BALANCE"
}
json
// Response 200
{
  "ok": true,
  "spent": 100,
  "rebate": 5,
  "newBalance": 180,
  "treasury": {
    "platform": 80,
    "protocol": 20
  }
}

Balance & Tiers

GET
/v1/users/{userId}

Get a user's current TISH balance, tier, and earn multiplier.

json
// Response 200
{
  "userId": "usr_abc123",
  "balance": 1250,
  "tier": "Curator",
  "tierThreshold": 500,
  "nextTier": "Pioneer",
  "nextTierAt": 2000,
  "multiplier": 1,
  "foundingMember": false,
  "createdAt": "2026-07-01T00:00:00Z"
}

Tier reference

Builder0 – 4990% rebate5/month AI credits
Curator500 – 1,9995% rebate25/month AI credits
Pioneer2,000 – 9,99910% rebate500/month AI credits
Architect10,000+20% rebate1,000/month AI credits

Webhooks

TISH notifies your platform in real-time when a user's tier changes or a spend event is confirmed. Configure your webhook URL in the Platform Dashboard (available Phase 2).

tish.earn.completedUser earned TISH on your platform
tish.spend.completedUser spent TISH on your platform
tish.tier.upgradedUser reached a new tier
tish.user.suspendedUser account suspended by TISH Protocol
typescript
// Verify webhook signature (Node.js)
import crypto from "crypto";

function verifyTISHWebhook(payload: string, sig: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(`sha256=${expected}`)
  );
}

Error Codes

400INVALID_REQUESTMissing or malformed request parameters
401UNAUTHORIZEDInvalid or missing API key
403PLATFORM_NOT_APPROVEDPlatform not signed or suspended
404USER_NOT_FOUNDuserId has no TISH account yet
409DUPLICATE_EVENTidempotencyKey already processed
422INSUFFICIENT_BALANCEUser balance too low to spend
422CAP_EXCEEDEDDaily earn cap reached for this action
422EARN_ON_PAYMENTEarn attempted on a payment event (blocked)
429RATE_LIMITEDToo many requests. Retry with backoff.
500INTERNAL_ERRORTISH server error. Retry with exponential backoff.

Rate Limits

Earn events
600 / min per platform
Spend events
300 / min per platform
Balance reads
1,200 / min per platform

Rate limit headers included in every response: X-RateLimit-Remaining and X-RateLimit-Reset. Implement exponential backoff on 429 responses.