Credit Wallet

Credits a wallet balance inside one project. Use this endpoint for manual top-ups, credit grants, or other externally confirmed funding events.

POST /v1/projects/:project_id/wallets/credit

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the wallet. The account_id or resolved subject route must belong to this project.

Request Body

{
  "account_id": "acct_xxx",
  "currency": "USD",
  "amount": "500.00",
  "source_type": "manual_topup",
  "source_id": "topup_20260629_001",
  "idempotency_key": "topup:t_001:acct_xxx:20260629_001"
}

Field	Required	Description
account_id	Conditionally	Billing account ID in the same project. Mutually exclusive with resolving the account from subject_type and subject_id. Recommended for wallet credits.
subject_type	Conditionally	Subject type used to resolve the account when account_id is not provided.
subject_id	Conditionally	Subject ID used to resolve the account when account_id is not provided.
currency	Yes	Currency to credit.
amount	Yes	Credit amount. Must be greater than 0. Use a JSON string for decimal precision.
source_type	No	Source type for the credit, for example manual_topup.
source_id	No	Source identifier from your system.
idempotency_key	No	Idempotency key. Length: 1-255 characters when provided. Repeated requests with the same key do not apply duplicate credits.

Notes

• Prefer passing account_id directly for top-up flows.
• Use a stable idempotency_key for retryable requests, up to 255 characters.
• Idempotency is scoped by tenant_id + project_id; the same key in another project is independent.
• Wallet balance mutations are serialized by the service for the affected tenant, project, account, and currency.