Currencies

Currencies are named tokens (code like "gems") with optional cap (max_balance) and auto-recharge rules. user_balances holds per-user state. Grants are performed atomically under a FOR UPDATE row lock with a pre-flight zero-row insert so first-time grants can't race.

Source: apps/api/src/routes/admin/currencies.ts.

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/currencies`	Create a currency definition.
GET	`/admin/projects/:projectId/currencies`	List currency definitions.
PATCH	`/admin/projects/:projectId/currencies/:currencyId`	Partial update.
DELETE	`/admin/projects/:projectId/currencies/:currencyId`	Delete.
POST	`/admin/projects/:projectId/currencies/grant`	Grant currency to a user (admin source).
GET	`/admin/projects/:projectId/currencies/transactions/:userId`	Paginated transaction history for a user.

POST /admin/projects/:projectId/currencies

Request

Field	Type	Required	Default
`code`	string	yes	—
`name`	string	yes	—
`description`	string	no	null
`is_premium`	boolean	no	false
`initial_balance`	number	no	0
`max_balance`	number	no	null (uncapped)
`auto_recharge_amount`	number	no	null
`auto_recharge_interval_hours`	number	no	null

Response 201

{
  "data": {
    "id": "…",
    "code": "gems",
    "name": "Gems",
    "is_premium": false,
    "initial_balance": 0,
    "max_balance": 9999
  }
}

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/currencies

developer auth

curl -X POST 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/currencies'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/currencies' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/currencies

{ "data": [{ "code": "gems", "name": "Gems", "is_premium": false }] }

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/currencies

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/currencies'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/currencies' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/currencies/:currencyId

Allowed fields: name, description, is_premium, initial_balance, max_balance, auto_recharge_amount, auto_recharge_interval_hours.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/currencies/%7B%7BcurrencyId%7D%7D

developer auth

curl -X PATCH 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/currencies/%7B%7BcurrencyId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/currencies/{currencyId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/currencies/:currencyId

{ "data": { "deleted": true } }

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/currencies/%7B%7BcurrencyId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/currencies/%7B%7BcurrencyId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/currencies/{currencyId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

POST /admin/projects/:projectId/currencies/grant

Grant currency to a user. Clamped to max_balance if set; a fully-clamped grant still returns 201 with a zero-delta currency_transactions row for auditability.

Request (`GrantCurrencyInput`)

Field	Type	Required	Description
`app_user_id`	uuid	yes	Recipient.
`currency_code`	string	yes	Must exist in `currency_definitions`.
`amount`	number	yes	Must be finite and > 0.
`reason`	string	no	Free-form reference id stored on the transaction.

Response 201

{
  "data": {
    "balance": 150,
    "transaction": {
      "id": "…",
      "app_user_id": "…",
      "currency_code": "gems",
      "amount": 50,
      "balance_after": 150,
      "transaction_type": "grant",
      "source": "admin",
      "reference_id": null,
      "created_at": "…"
    }
  }
}

Errors

400 INVALID_AMOUNT — amount isn't a positive finite number.
404 CURRENCY_NOT_FOUND — unknown currency_code.
500 GRANT_FAILED.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/currencies/grant

developer auth

curl -X POST 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/currencies/grant'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/currencies/grant' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/currencies/transactions/:userId

Paginated transaction history for a single user, most recent first.

Query

Param	Default
`limit`	50
`offset`	0

Response 200

{
  "data": [
    {
      "id": "…",
      "currency_code": "gems",
      "amount": 50,
      "balance_after": 150,
      "transaction_type": "grant"
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 50
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/currencies/transactions/%7B%7BuserId%7D%7D

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/currencies/transactions/%7B%7BuserId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/currencies/transactions/{userId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

On this page