# 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

```http
POST /v1/auth/register
POST /v1/auth/login
```

User tokens:

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

---

## User

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

---

## Actor

Actors represent *authority*, not users.

```json
{
  "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.

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

Used as:

```http
Authorization: Bearer act_live_abc123
```

---

## Link Codes

### Request a Link Code

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

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

```json
{
  "expires_in": 300
}
```

Response:

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

---

### Consume a Link Code

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

```http
POST /v1/links/consume
```

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

Response:

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

---

## Transactions

Only actors or the system may create transactions.

```http
POST /v1/transactions
Authorization: Bearer ACTOR_TOKEN
```

```json
{
  "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

```json
{
  "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)

```http
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.

---