Credits

Assimetria OS uses a dollar-denominated credit system for metered usage. Credits are purchased in advance and consumed as agents execute tasks, make API calls, and use compute resources.

Credit balance

Retrieve the current credit balance for the authenticated user or organization:

curl https://api.orkosi.com/api/credits/balance \
  -H "Authorization: Bearer TOKEN"

Response:

{
  "data": {
    "balance": 142.50,
    "currency": "USD"
  }
}

Credit packages

List available credit packages:

curl https://api.orkosi.com/api/credits/packages

Response:

{
  "data": [
    { "id": "starter", "amount": 25, "price": 25, "currency": "USD" },
    { "id": "pro", "amount": 100, "price": 90, "currency": "USD" },
    { "id": "teams", "amount": 500, "price": 400, "currency": "USD" }
  ]
}

Purchasing credits

Initiate a credit purchase via Stripe checkout:

curl -X POST https://api.orkosi.com/api/credits/purchase \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"package_id": "pro"}'

Depositing credits (admin)

Admins can directly deposit credits to an account:

curl -X POST https://api.orkosi.com/api/credits/deposit \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00, "description": "Manual top-up"}'

Debiting credits

Debit credits for a usage event:

curl -X POST https://api.orkosi.com/api/credits/debit \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1.25, "description": "Agent run #4521"}'

Transaction history

List credit transactions with pagination:

curl "https://api.orkosi.com/api/credits/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer TOKEN"

Response:

{
  "data": [
    {
      "id": 1,
      "type": "deposit",
      "amount": 100.00,
      "balance_after": 242.50,
      "description": "Pro package purchase",
      "created_at": "2026-04-15T10:30:00Z"
    },
    {
      "id": 2,
      "type": "debit",
      "amount": -1.25,
      "balance_after": 241.25,
      "description": "Agent run #4521",
      "created_at": "2026-04-15T11:00:00Z"
    }
  ],
  "meta": { "total": 156, "limit": 20, "offset": 0 }
}

Usage summary

Get an aggregated usage summary:

curl https://api.orkosi.com/api/credits/usage-summary \
  -H "Authorization: Bearer TOKEN"

Endpoints summary

Method	Path	Auth	Description
GET	/credits/balance	Yes	Current credit balance
POST	/credits/deposit	Admin	Deposit credits
POST	/credits/debit	Yes	Debit credits for usage
GET	/credits/transactions	Yes	Transaction history (paginated)
GET	/credits/usage-summary	Yes	Aggregated usage summary
GET	/credits/packages	No	List available credit packages
POST	/credits/purchase	Yes	Purchase credits via Stripe

Token-based usage

In addition to dollar-denominated credits, Assimetria OS tracks token consumption for LLM operations. See the token endpoints:

Method	Path	Auth	Description
GET	/tokens/balance	Yes	Current token balance
GET	/tokens/transactions	Yes	Token transaction history
POST	/tokens/consume	Yes	Record token consumption
GET	/tokens/plans	No	Available token plans
POST	/tokens/checkout	Yes	Purchase tokens via Stripe
POST	/tokens/grant	Yes	Grant tokens (admin)