크레딧 원장 목록
GET /v1/credit-ledger
GET https://api.k-otp.dev/v1/credit-ledger개요
Returns an audit projection of mutations of the wallet the key spends from: for an organization wallet, its credit top-ups and clawbacks plus only the authenticated app's per-issue debits and refunds (appId attributes app-level entries). amountDelta is signed (debits are negative) and balanceAfter is the wallet balance after the entry. Internal billing references, external payment references, and initiator metadata are omitted; issueId is present only for issue-linked entries.
Results are ordered newest first (createdAt descending, ties broken by id) and keyset-paginated. Pass limit (1-100, default 50) and, for subsequent pages, the opaque cursor returned as nextCursor; nextCursor is omitted on the last page. Cursors are bound to the endpoint that issued them and must be sent unchanged. Keep the same filters while paging.
Optional createdFrom/createdTo (RFC 3339 date-time) select the half-open range [createdFrom, createdTo); when both are given createdFrom must be earlier than createdTo. entryType filters by entry type.
A sk_test_ key never reads the real ledger: it always gets an empty page (items: []).
Requires an sk_ secret key; pk_ public keys are rejected with 403.
인증
| 허용 키 | 필요 scope | 대체 허용 scope |
|---|---|---|
sk_ | otp:ledger:read | otp:dashboard:read, otp:read, * |
파라미터
| 이름 | 위치 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
limit | query | integer | Page size: 1-100 items. Defaults to 50 when omitted. | |
cursor | query | string | nextCursor from the previous page. | |
entryType | query | "clawback" | "credit" | "debit" | "promo_credit" | "promo_expire" | "promo_revoke" | "refund" | Filter by entry type. | |
createdFrom | query | string (date-time) | Inclusive lower bound on createdAt. | |
createdTo | query | string (date-time) | Exclusive upper bound on createdAt; must be later than createdFrom. |
응답 (200)
One page of ledger entries, newest first.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
items | object[] | 예 | |
nextCursor | string | Cursor for the next page; absent on the last page. |
오류 응답
모든 오류는 { defined, code, status, message, data? } 형태입니다. 자세한 내용은 오류를 참고하세요.
| 상태 | code | 설명 |
|---|---|---|
| 400 | BAD_REQUEST | invalid query, limit outside 1-100, malformed cursor, a cursor issued by a different endpoint, or createdFrom not earlier than createdTo. |
| 401 | UNAUTHORIZED | the Authorization: Bearer credential is missing, malformed, inactive, or rejected by introspection. |
| 403 | FORBIDDEN | the credential lacks otp:ledger:read (or an accepted alias), or a pk_ public key was used. Public keys are limited to issue/verify. |
| 409 | CONFLICT | the request conflicts with the current state of the resource. |
| 429 | TOO_MANY_REQUESTS | only for test-mode (sk_test_) keys, whose reads are metered (data.limit: perKey per minute or perKeyDaily per day, data.policy: platform). Wait data.retryAfterMs milliseconds (Retry-After in seconds). Live keys are never rate limited on reads. |
| 500 | INTERNAL_SERVER_ERROR | unexpected server failure. Undefined errors (defined: false) use the same envelope. |
| 503 | SERVICE_UNAVAILABLE | credential introspection or a downstream dependency is temporarily unavailable. Retry with backoff. |
요청 예시
curl "https://api.k-otp.dev/v1/credit-ledger" \
-H "Authorization: Bearer $KOTP_SECRET_KEY"