Shard Currency API#

A very small, fictional currency API for games and community systems.

• One balance per user
• No real-world money
• Users can never change their own balance
• Balance changes are performed only by actors via scoped tokens

Core Concepts#

User#

A human account with exactly one balance.

Actor#

A trusted external service (Minecraft server, Discord bot, admin tool, etc.) that may create transactions.

Transaction#

An immutable record of a balance change.

Link Code#

A short-lived, one-time code used to create an actor and issue its token.

Authentication#

User Auth#

POST /v1/auth/register
POST /v1/auth/login

User tokens:

• allow viewing balance
• allow viewing transactions
• allow requesting link codes
• never allow transactions

User#

{
  "id": "usr_01HXYZ",
  "email": "user@example.com",
  "balance": 420,
  "created_at": "2025-09-01T12:00:00Z"
}

Actor#

Actors represent authority, not users.

{
  "id": "act_01HABC",
  "name": "Survival SMP",
  "permissions": {
    "max_single_transaction": 100,
    "daily_cap": 5000,
    "allow_negative": true
  },
  "expires_at": "2025-10-10T00:00:00Z"
}

Notes:

• Permissions are defined by the API / API_KEY holder
• Public clients cannot choose permissions

Actor Token#

Issued when a link code is consumed.

{
  "actor_id": "act_01HABC",
  "token": "act_live_abc123",
  "expires_at": "2025-10-10T00:00:00Z"
}

Used as:

Authorization: Bearer act_live_abc123

Link Codes#

Request a Link Code#

Used by a trusted UI (e.g. Discord bot using API_KEY).

POST /v1/links/request
Authorization: ApiKey ${API_KEY}

{
  "expires_in": 300
}

Response:

{
  "code": "Z9FQ-2KDL"
}

Consume a Link Code#

Used by the external service (e.g. Minecraft server).

POST /v1/links/consume

{
  "code": "Z9FQ-2KDL",
  "name": "Survival SMP"
}

Response:

{
  "actor_id": "act_01HABC",
  "token": "act_live_abc123",
  "expires_at": "2025-10-10T00:00:00Z"
}

Transactions#

Only actors or the system may create transactions.

POST /v1/transactions
Authorization: Bearer ACTOR_TOKEN

{
  "user_id": "usr_01HXYZ",
  "amount": 25,
  "reason": "Quest reward"
}

Rules:

• amount > 0 → credit
• amount < 0 → debit
• Amount must be within actor limits
• Transactions are append-only

Transaction Record#

{
  "id": "txn_01HZAB",
  "user_id": "usr_01HXYZ",
  "amount": 25,
  "reason": "Quest reward",
  "actor_id": "act_01HABC",
  "created_at": "2025-09-10T18:42:00Z"
}

API_KEY (Host-Level Access)#

Authorization: ApiKey ${API_KEY}

Capabilities:

• Create link codes
• Create actors directly
• Create transactions without actor limits

All actions are still logged.

⚠️ Never expose this key publicly.