Gift Studio Build Guide

0

Prerequisites

You need a SocialOS API key to use these endpoints. If you don't have one yet, follow the Agent Quick Start to get your free sandbox key in under 2 minutes.

Base URL: https://sandbox.socialos.io/v2

1

Create Gifts

Create a new gift campaign with a name, reward tier, point value, and optional badge inclusion. Set an expiration date to create time-limited promotions that drive engagement.

POST /gamification/gifts

curl

curl -X POST https://sandbox.socialos.io/v2/gamification/gifts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Pack",
    "tier": "gold",
    "reward": 500,
    "badge": true,
    "expires": "2026-03-20T00:00:00Z"
  }'

Response 200 OK

{
  "gift_id": "gift_w3lc",
  "name": "Welcome Pack",
  "tier": "gold",
  "reward": 500,
  "badge_included": true,
  "expires": "2026-03-20T00:00:00Z",
  "created_at": "2026-02-20T14:00:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/gamification/gifts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "Welcome Pack",
        "tier": "gold",
        "reward": 500,
        "badge": True,
        "expires": "2026-03-20T00:00:00Z"
    }
)
result = resp.json()
print(result)

2

Assign Tiers

When a user redeems a gift, update their tier score using the gamification engine. The system tracks cumulative points, computes the current tier name, and returns the updated rank.

POST /gamification/score

curl

curl -X POST https://sandbox.socialos.io/v2/gamification/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "alice.kred",
    "metric": "tier",
    "action": "gift_redeemed",
    "value": 500
  }'

Response 200 OK

{
  "userId": "alice.kred",
  "metric": "tier",
  "previous": 200,
  "current": 700,
  "tier_name": "gold",
  "rank": 5,
  "updated_at": "2026-02-20T14:05:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/gamification/score",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "userId": "alice.kred",
        "metric": "tier",
        "action": "gift_redeemed",
        "value": 500
    }
)
result = resp.json()
print(result)

3

Audit Currency

Pull analytics on gift redemptions and virtual currency flow over a time window. Returns aggregate totals, unique recipients, the most popular tier, and a daily breakdown for trend analysis.

GET /analytics

curl

curl "https://sandbox.socialos.io/v2/analytics?type=currency&metric=gifts_redeemed&window=7d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "type": "currency",
  "metric": "gifts_redeemed",
  "window": "7d",
  "summary": {
    "total_gifts": 142,
    "total_value": 28400,
    "unique_recipients": 98,
    "top_tier": "gold"
  },
  "daily": [
    { "date": "2026-02-20", "count": 23, "value": 4600 },
    { "date": "2026-02-19", "count": 19, "value": 3800 }
  ]
}

Python

import requests

resp = requests.get(
    "https://sandbox.socialos.io/v2/analytics",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "type": "currency",
        "metric": "gifts_redeemed",
        "window": "7d"
    }
)
result = resp.json()
print(result)

4

Complete Agent

A complete Gift Studio agent that creates a gift campaign, assigns a tier to a user who redeems it, and audits currency stats in one script.

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://sandbox.socialos.io/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_gift(name: str, tier: str, reward: int, badge: bool, expires: str) -> dict:
    """Create a new gift campaign."""
    resp = requests.post(f"{BASE}/gamification/gifts", headers=HEADERS, json={
        "name": name,
        "tier": tier,
        "reward": reward,
        "badge": badge,
        "expires": expires
    })
    return resp.json()


def assign_tier(user_id: str, action: str, value: int) -> dict:
    """Update a user's tier score after a gift redemption."""
    resp = requests.post(f"{BASE}/gamification/score", headers=HEADERS, json={
        "userId": user_id,
        "metric": "tier",
        "action": action,
        "value": value
    })
    return resp.json()


def audit_currency(metric: str, window: str) -> dict:
    """Pull currency analytics for a given time window."""
    resp = requests.get(f"{BASE}/analytics", headers=HEADERS, params={
        "type": "currency",
        "metric": metric,
        "window": window
    })
    return resp.json()


def main():
    # Step 1 - Create a gift campaign
    gift = create_gift("Welcome Pack", "gold", 500, badge=True, expires="2026-03-20T00:00:00Z")
    print(f"Gift created: {gift['name']} (ID: {gift['gift_id']})")
    print(f"Tier: {gift['tier']} | Reward: {gift['reward']} pts | Badge: {gift['badge_included']}")

    # Step 2 - User redeems the gift, update their tier
    tier = assign_tier("alice.kred", "gift_redeemed", gift["reward"])
    print(f"\nTier updated for alice.kred: {tier['previous']} -> {tier['current']}")
    print(f"Current tier: {tier['tier_name']} (rank #{tier['rank']})")

    # Step 3 - Audit currency flow over the past week
    audit = audit_currency("gifts_redeemed", "7d")
    summary = audit["summary"]
    print(f"\nCurrency audit ({audit['window']}):")
    print(f"Total gifts: {summary['total_gifts']} | Value: {summary['total_value']}")
    print(f"Unique recipients: {summary['unique_recipients']} | Top tier: {summary['top_tier']}")


if __name__ == "__main__":
    main()

5

Next Steps

Continue building with these related guides and resources.

Build Virtual Assets

Mint badges, transfer items, and track ownership.

Build a Score System

Compute trust scores, rank leaderboards, and flag anomalies.

Agent Quick Start

Authentication, base setup, and your first API call in under 5 minutes.

Full API Reference

Complete documentation for every endpoint, parameter, and response type.

Pricing

Compare plans and find the right tier for your agent's usage volume.