Skip to content
HarperHarborDocs

Credits balance and activity

GET
/open/v1/me/wallet
curl --request GET \
  --url https://api.harperharbor.com/open/v1/me/wallet \
  --header 'Authorization: Bearer <token>'

Returns the caller’s credits (spendable, permanent, time-limited and held by running turns), upcoming expiries, and the balance activity in this app, newest first. Top-up is not available through the Open API; send the user to the main site.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
>= 1 <= 50

Entries per page, 1 to 50.

cursor
string

Opaque nextCursor from a previous page. Malformed → 400 invalid_cursor.

Responses

Section titled “Responses”

200

Section titled “200”

Wallet.

Media typeapplication/json
object
available
required

Credits the caller can spend now: permanent plus time-limited, less what running turns hold.

integer format: int64
permanent
required

Credits that never expire.

integer format: int64
expiring
required

Time-limited credits in total.

integer format: int64
reserved
required

Credits held by turns still running; released or charged when they finish.

integer format: int64
expiries
required

Time-limited credits by expiry and source, soonest first, at most 10; batches with the same expiry and source are merged. The expiring total keeps its meaning.

Array<object>
object
amount
required

Credits.

integer
expiresAt
required

When they expire.

string format: date-time
kind
required

Where the credits came from: welcome — sign-up gift; event — campaign credits; checkin, task, newcomer or referral — rewards; other — anything else.

string
Allowed values: welcome event checkin task newcomer referral other
ledger
required

Balance activity in this app, newest first.

Array<object>
object
id
required

Entry identifier.

string
at
required

When the balance changed.

string format: date-time
reason
required

Why the balance changed: purchase, grant, campaign, chat, api, image, speech, video, refund, expire, adjust, redeem, rebate, referral or signup. Map it to your own copy.

string
amount
required

Credits added (positive) or taken (negative).

integer format: int64
rewardKind

Present on credits from app rewards: checkin, task, newcomer or referral.

string
Allowed values: checkin task newcomer referral
expiresAt

When these reward credits expire. Absent on expire entries.

string format: date-time
playerNote

Optional original-language explanation for a platform grant. Historical grants may omit it. Internal operator notes are never returned.

string
<= 200 characters
rankHonor
object
zone
required
string
Allowed values: clean all
window
required
string
Allowed values: day week month
band
required
integer
Allowed values: 1 3 10
nextCursor
required

Opaque cursor for the next page of ledger; empty when there is none.

string
Example
{
  "expiries": [
    {
      "kind": "welcome"
    }
  ],
  "ledger": [
    {
      "rewardKind": "checkin",
      "rankHonor": {
        "zone": "clean",
        "window": "day",
        "band": 1
      }
    }
  ]
}

401

Section titled “401”

unauthorized.

Media typeapplication/json
object
error
required

Error code (snake_case) or, for legacy handlers, a free-text/localized message.

string
message

Human-readable sentence. Present only on middleware errors and /me, /me/wallet.

string
retryable

Whether retrying may succeed. Present only on middleware errors, /me, /me/wallet and service/share routes.

boolean
required_context_tier

Only on a first-turn context_capacity_exceeded: the smallest context tier that fits the whole card with room to talk. Save it as context in player settings and resend. Absent when no tier fits.

integer
>= 1 <= 5
required_context_tokens

The token budget of required_context_tier for the selected model, for display.

integer
constant_lore_trim_fits

Only on a first-turn context_capacity_exceeded: whether saving trimConstantLore=true lets the card play at the current tier. Absent on mid-conversation capacity errors.

boolean
credits_needed

Only on insufficient_credits: the credits this turn needs before it can start. Absent when the refusal came without an estimate.

integer
credits_available

Only on insufficient_credits: the credits the wallet could set aside for it.

integer
Examplegenerated
{
  "error": "example",
  "message": "example",
  "retryable": true,
  "required_context_tier": 1,
  "required_context_tokens": 1,
  "constant_lore_trim_fits": true,
  "credits_needed": 1,
  "credits_available": 1
}

404

Section titled “404”

not_found — account not found.

Media typeapplication/json
object
error
required

Error code (snake_case) or, for legacy handlers, a free-text/localized message.

string
message

Human-readable sentence. Present only on middleware errors and /me, /me/wallet.

string
retryable

Whether retrying may succeed. Present only on middleware errors, /me, /me/wallet and service/share routes.

boolean
required_context_tier

Only on a first-turn context_capacity_exceeded: the smallest context tier that fits the whole card with room to talk. Save it as context in player settings and resend. Absent when no tier fits.

integer
>= 1 <= 5
required_context_tokens

The token budget of required_context_tier for the selected model, for display.

integer
constant_lore_trim_fits

Only on a first-turn context_capacity_exceeded: whether saving trimConstantLore=true lets the card play at the current tier. Absent on mid-conversation capacity errors.

boolean
credits_needed

Only on insufficient_credits: the credits this turn needs before it can start. Absent when the refusal came without an estimate.

integer
credits_available

Only on insufficient_credits: the credits the wallet could set aside for it.

integer
Examplegenerated
{
  "error": "example",
  "message": "example",
  "retryable": true,
  "required_context_tier": 1,
  "required_context_tokens": 1,
  "constant_lore_trim_fits": true,
  "credits_needed": 1,
  "credits_available": 1
}