Credits

EFFECT credits are the currency used to pay for jobs. All balance changes, including top-ups, job debits, and refunds, are recorded as immutable ledger entries.

1 EFFECT = 1,000,000 lamports. All amounts in the API are returned as lamport strings to preserve precision.

Credit lifecycle

Event	Type	What triggers it
Team adds funds	`topup`	Manual admin top-up
Job created	`debit`	`POST /jobs` with the full cost reserved upfront
Job creation fails	`refund`	Auto-refund if the job fails after debit

List transactions

GET /v1/credits/transactions

Returns your full credit history, newest first.

curl

curl -s "https://api.effect.ai/v1/credits/transactions" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

With pagination

curl

curl -s "https://api.effect.ai/v1/credits/transactions?limit=10&offset=0" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

Query parameters

Parameter	Default	Max	Description
`limit`	100	1000	Number of entries to return
`offset`	0	None	Number of entries to skip

Response 200

{
  "transactions": [
    {
      "id": "01JQKX3Z8VFNWRB2TGHM4Y5P6C",
      "type": "refund",
      "amount": "5000000",
      "balanceAfter": "20000000",
      "jobId": "01JQKX3Z8VFNWRB2TGHM4Y5P6B",
      "note": "job 01JQKX3Z8VFNWRB2TGHM4Y5P6B cancelled with 10 unfinished tasks",
      "timestamp": 1750000200000
    },
    {
      "id": "01JQKX3Z8VFNWRB2TGHM4Y5P6B",
      "type": "debit",
      "amount": "10000000",
      "balanceAfter": "15000000",
      "jobId": "01JQKX3Z8VFNWRB2TGHM4Y5P6B",
      "note": "job 01JQKX3Z8VFNWRB2TGHM4Y5P6B (20 tasks)",
      "timestamp": 1750000100000
    },
    {
      "id": "01JQKX3Z8VFNWRB2TGHM4Y5P6A",
      "type": "topup",
      "amount": "25000000",
      "balanceAfter": "25000000",
      "note": "manual top-up",
      "timestamp": 1750000000000
    }
  ],
  "total": 3,
  "limit": 100,
  "offset": 0,
  "currency": "EFFECT",
  "lamportsPerEffect": 1000000
}

Field	Description
`type`	`"topup"`, `"debit"`, or `"refund"`
`amount`	Amount in lamports (string). Divide by `lamportsPerEffect` to get EFFECT
`balanceAfter`	Account balance immediately after this entry, in lamports
`jobId`	The job this entry relates to; omitted for top-ups
`note`	Human-readable description of why the change occurred (optional)
`timestamp`	Unix timestamp in milliseconds

Reading the example above

Entry	Amount	EFFECT	Balance after
Top-up	+25,000,000	+25 EFFECT	25 EFFECT
Debit (20 tasks × 0.5)	-10,000,000	-10 EFFECT	15 EFFECT
Refund (10 unfinished × 0.5)	+5,000,000	+5 EFFECT	20 EFFECT

The 10 completed tasks consumed 5 EFFECT; the 10 unfinished tasks were refunded 5 EFFECT. balanceAfter reflects the exact balance immediately after each ledger write.