Skip to content

REM Credits API

The /internal/v1 contract apps use to read balances, quote, hold, settle and release REM Credits, with examples.

REM Credits are kept by REM Payments, per (app, payer). Apps talk to the ledger at https://rempayments.com/internal/v1 (OpenAPI reference at /internal/v1/docs). The app is always the one the service token was minted for, never a field you can choose: a request naming another app answers 403 app_mismatch.

Get a service token

# apps on the REM Payments SDK: the org-pinned API token (write scope) they linked with
curl -X POST https://rempayments.com/internal/v1/auth/token -H "Content-Type: application/json" \
  -d '{"app": "vibecoder", "api_token": "ptk_..."}'

# older apps (REM Interns, REM Learners): the secret from the app's Credits tab
curl -X POST https://rempayments.com/internal/v1/auth/token -H "Content-Type: application/json" \
  -d '{"app": "rem_interns", "secret": "..."}'

Answer: {"access_token": "...", "token_type": "Bearer", "expires_in": 600, "app": "..."}. A wrong code, secret or token is always the same vague 401 {"error": "invalid_client"}. Making a new secret ends every token minted with the old one. Errors are {"error": "<code>", "detail": "<sentence>"}.

The payer

The payer id is the external_id your app sent at checkout. For SDK apps it is <app>:<payer>, for example rch:company:5 or vibecoder:org:<uid>. The same string is the user_id of every call below. A payment whose customer has no external_id grants nothing.

Reserve, run, settle

T="Authorization: Bearer $ACCESS_TOKEN"

# 1. can they afford it?
curl -X POST https://rempayments.com/internal/v1/quote -H "$T" -H "Content-Type: application/json" \
  -d '{"user_id": "vibecoder:org:42", "app": "vibecoder", "feature": "build", "run_mode": "NOW", "input_tokens": 0}'

# 2. reserve before the work (idempotent by key)
curl -X POST https://rempayments.com/internal/v1/holds -H "$T" -H "Content-Type: application/json" \
  -d '{"user_id": "vibecoder:org:42", "app": "vibecoder", "feature": "build", "idempotency_key": "build-7731", "run_mode": "NOW"}'
# 201 {"hold_id": "...", "rem_held": 100, "rem_available_after": 900, ...}
# 402 {"error": "insufficient_balance", "required": 100, "available": 40, "shortfall": 60, "topup_url": "..."}

# 3. mark it started, run the AI call, then settle with the real usage (idempotent by call_id)
curl -X POST https://rempayments.com/internal/v1/holds/$HOLD/start -H "$T" -H "Content-Type: application/json" -d '{}'
curl -X POST https://rempayments.com/internal/v1/holds/$HOLD/settle -H "$T" -H "Content-Type: application/json" \
  -d '{"usage": {"input_tokens": 5120, "output_tokens": 830}, "call_id": "call-7731", "upstream_model": "claude-sonnet"}'

# or give the credits back if the call failed
curl -X POST https://rempayments.com/internal/v1/holds/$HOLD/release -H "$T" -H "Content-Type: application/json" \
  -d '{"reason": "provider timeout", "call_failed": true}'

usage accepts the provider's usage object as it comes (OpenAI-style prompt_tokens, Anthropic input_tokens with cache reads, Gemini usageMetadata) or the parts input_cache_miss, input_cache_hit, output. A settlement is priced at the price version pinned on the hold. Holds left open past the app's hold time are released by the worker.

Other routes

Route

Use

POST /wallets/provision

Create the payer's account (sub, issuer, email, name); gives the free allowance once

GET /wallets/{user_id}

rem_available, rem_held, tier_access, is_frozen, plan_code, low_balance

GET /wallets/{user_id}/overview

Balance by lot, usage, spend per feature, and this app's plans and packs to buy

GET /wallets/{user_id}/ledger?limit=&offset=&kind=

The payer's history for your app's own credits page

POST /usage

Report usage after the fact (by call_id); never refused, a shortfall becomes owed credits

GET /charging-status?user_id=

Whether charging is on, or waived for this payer

Events

credits.granted and credits.clawed_back reach your Payments webhook endpoints (app, payer, credits, source, reason, balance, and for claw-backs refund_id, written_off, owed). Use them to drop a cached balance.

What grants credits (plan cycles, rollover, top-ups, trials, free allowance) is described in the user guide: REM Credits.

Last updated 18 Nov 2026

REM Credits API · REM Platforms Blog