Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.compose.market/llms.txt

Use this file to discover all available pages before exploring further.

A session is a wallet budget on one chain. The API stores live budget state, reserves part of that budget before work starts, and settles or releases the reservation when the request ends. The spendable amount is: 
budgetLimit - budgetUsed - budgetReserved

​
Read session state

GET /api/session
x-session-user-address: 0x...
x-chain-id: 43113
Active response: 
{
  "hasSession": true,
  "keyId": "f65a...",
  "budgetLimit": "1000000",
  "budgetUsed": "12000",
  "budgetLocked": "0",
  "budgetRemaining": "988000",
  "expiresAt": 1790000000000,
  "chainId": 43113,
  "status": {
    "isActive": true,
    "isExpired": false,
    "expiresInSeconds": 3600,
    "budgetPercentRemaining": 98.8
  }
}
Inactive response: 
{
  "hasSession": false,
  "reason": "expired"
}
Common reasons are none, expired, revoked, budget_exhausted, missing_budget_state, and invalid_key.

​
Reserve and settle

The reservation step matters. A long streaming request can hold budget while it runs, so two parallel calls cannot spend the same remaining amount.

​
Session events

GET /api/session/events?userAddress=0x...&chainId=43113
The endpoint streams session status events over Server-Sent Events. When the active session becomes unavailable, the API sends: 
event: session-expired
data: {"reason":"expired","userAddress":"0x...","chainId":43113}

​
Response headers

HeaderMeaning
x-payment-methodsession-bypass for active session requests.
x-session-budget-limitTotal budget.
x-session-budget-usedSettled usage.
x-session-budget-lockedReserved amount.
x-session-budget-remainingSpendable amount left.
x-session-statusWarning such as budget-low, budget-depleted, or expiring-soon.
x-compose-session-invalidWhy a session key no longer works.