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.

Endpoints

POST /admin/projects/:projectId/currencies

Request

When initial_balance > 0, that starting amount is spendable. On a user's first grant or spend of this currency, Amba lazily credits the starting balance into the ledger as a system transaction before applying the operation, so the balance read and the summed transaction history stay in agreement and the starting amount can be spent immediately. A currency with initial_balance of 0 credits nothing — the user starts empty.

Response 201

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

Try it:

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

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:

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

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:

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

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:

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

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)

Response 201

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

Response 200 (idempotent replay)

A repeat with a previously-seen idempotency_key (same user + currency) returns the original transaction with "idempotent_replay": true and HTTP 200 — the balance is not changed. See Idempotency.

Errors

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

Try it:

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

Curl:

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

POST /admin/projects/:projectId/currencies/spend

Debit currency from a user. Atomic — returns 400 INSUFFICIENT_FUNDS if the balance is too low. No partial debit; the request either fully succeeds or fully fails.

The ledger records the spend as a negative amount (signed delta), so SUM(amount) across a user's transactions reconstructs the current balance.

Request (SpendCurrencyInput)

Response 201

{
  "data": {
    "balance": 70,
    "idempotent_replay": false,
    "transaction": {
      "id": "…",
      "app_user_id": "…",
      "currency_code": "gems",
      "amount": -30,
      "balance_after": 70,
      "transaction_type": "spend",
      "source": "admin",
      "reference_id": "ai_generation",
      "created_at": "…"
    }
  }
}

Response 200 (idempotent replay)

A repeat with a previously-seen idempotency_key (same user + currency) returns the original transaction with "idempotent_replay": true and HTTP 200 — the balance is not changed. See Idempotency.

Errors

• 400 INVALID_AMOUNT — amount isn't a positive finite number.
• 400 INSUFFICIENT_FUNDS — current balance is below amount. The error message includes both values. No key is stored, so the same idempotency_key may be retried after the user tops up.
• 404 CURRENCY_NOT_FOUND — unknown currency_code.
• 500 SPEND_FAILED.

Try it:

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

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/currencies/spend' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
        "app_user_id": "…",
        "currency_code": "gems",
        "amount": 30,
        "reason": "ai_generation"
      }'

Idempotency

Both grant and spend accept an optional idempotency_key (string, ≤255 chars). Sending the same key again for the same app_user_id + currency_code makes the operation exactly-once:

• The first request applies the balance change and responds 201 with "idempotent_replay": false.
• Any later request with the same key returns the original transaction unchanged, responds 200 with "idempotent_replay": true, and does not re-apply the delta.

The key is permanent — it's anchored to the ledger row it created, with no expiry window. The caller controls the dedup window through what they encode into the key. To cap a reward at "one grant per share per day," embed the date: idempotency_key: "share:{userId}:{yyyy-mm-dd}". The first call that day lands; the rest are no-op replays; the next day's key is different so the grant lands again — no guard collection of your own required.

A spend that fails with INSUFFICIENT_FUNDS stores no key (no ledger row was written), so the same key can be retried after the user tops up.

The same idempotency_key field is available on the amba_currencies_grant and amba_currencies_spend MCP tools, with identical semantics.

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

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

Query

Response 200

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

Try it:

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

Curl:

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