Consumer Session — POST /api/consumer/session

The consumer session endpoint is the wallet-first entry point for the FlareHQ consumer product. There is no email or password — a wallet address is the account. POST with an empty body creates a brand-new Circle-managed wallet and account; POST with a walletAddress connects an existing external wallet. Either way the response issues a signed JWT in a consumer_token cookie that lasts 30 days. The same path also hosts GET (session check) and DELETE (sign out).

Endpoint

POST   https://flarehq.xyz/api/consumer/session
GET    https://flarehq.xyz/api/consumer/session
DELETE https://flarehq.xyz/api/consumer/session

Request

Headers

Header	Value
`Content-Type`	`application/json` — required (POST)

No authentication is required to create a session — this endpoint is the onboarding step.

POST Body Parameters

string

Connect an existing external wallet. Must be a valid EVM 0x... address. When omitted, FlareHQ provisions a brand-new Circle-managed wallet instead.

Response

boolean

true on a successful session creation.

object

The consumer account behind the session.

Show account fields

string

Unique consumer account identifier.

string

The account’s wallet address — either the connected external address or the newly provisioned Circle-managed address.

The response also sets the consumer_token cookie (HttpOnly, SameSite=Lax, 30-day expiry). Browsers store and resend it automatically; protected consumer endpoints (balance, activity) require it.

GET — Session check

Returns the account decoded from the consumer_token cookie, for page-load session checks. Response body mirrors the POST body:

{
  "success": true,
  "account": {
    "id": "6d1e2f3a-9c8b-4a7f-b0e5-8d2c4f6a1b3e",
    "walletAddress": "0x4a2F1b9c7dE03A6b8C5f2e9D1a4c7B6e3F9d2A8"
  }
}

DELETE — Sign out

Clears the consumer_token cookie and returns:

{
  "success": true
}

Examples

curl -X POST https://flarehq.xyz/api/consumer/session \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{}'

curl -X POST https://flarehq.xyz/api/consumer/session \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "walletAddress": "0xAbCd1234ef5678901234AbCd1234ef5678901234"
  }'

const res = await fetch('https://flarehq.xyz/api/consumer/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});

const { success, account } = await res.json();
// The consumer_token cookie is set on the response

Success Response

{
  "success": true,
  "account": {
    "id": "6d1e2f3a-9c8b-4a7f-b0e5-8d2c4f6a1b3e",
    "walletAddress": "0x4a2F1b9c7dE03A6b8C5f2e9D1a4c7B6e3F9d2A8"
  }
}

Error Responses

{
  "success": false,
  "error": "Not a valid wallet address."
}

{
  "success": false,
  "error": "No session."
}

{
  "success": false,
  "error": "Invalid or expired session."
}

Notes

Sessions last 30 days so consumers do not have to re-onboard often. If a consumer’s cookie expires, simply call POST again with their existing walletAddress to refresh the session — existing external-wallet accounts are reused, and their lastSeenAt is updated.

Real fund custody lives in Circle for CIRCLE-type wallets, while EXTERNAL wallets are non-custodial by nature. The session mechanism itself is identical either way.

Calling POST with an empty body always provisions a new Circle wallet. To resume an existing account, always pass the walletAddress.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Consumer Session — POST /api/consumer/session

Endpoint

Request

Headers

POST Body Parameters

Response

GET — Session check

DELETE — Sign out

Examples

Success Response

Error Responses

Notes

​Endpoint

​Request

​Headers

​POST Body Parameters

​Response

​GET — Session check

​DELETE — Sign out

​Examples

​Success Response

​Error Responses

​Notes

Endpoint

Request

Headers

POST Body Parameters

Response

GET — Session check

DELETE — Sign out

Examples

Success Response

Error Responses

Notes