Skip to main content

​
Overview

The Laso Finance API uses two authentication mechanisms:
  1. x402 payment headers — For paywalled endpoints (/auth, /get-card, /send-payment). Your wallet address is extracted from the payment header to identify you. No API key needed.
  2. Bearer tokens — For free authenticated endpoints (/get-card-data). Pass an id_token as a Bearer token in the Authorization header.

​
Getting tokens

Call GET /auth (costs $0.001 USDC) or GET /get-card to receive auth credentials: 
{
  "auth": {
    "id_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "AMf-vBx4N2...",
    "expires_in": "3600"
  },
  "user_id": "0xabc123..."
}
FieldDescription
id_tokenFirebase ID token. Use as Bearer token for authenticated endpoints. Expires after ~1 hour.
refresh_tokenLong-lived token for getting new id_tokens without paying again.
expires_inToken lifetime in seconds (typically 3600 = 1 hour).
user_idYour user ID, derived from your wallet address (lowercased).

​
Using tokens

Pass the id_token as a Bearer token in the Authorization header: 
curl https://laso.finance/get-card-data?card_id=O-01ABC123 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

​
Refreshing tokens

When your id_token expires, use POST /auth with grant_type: "refresh_token" to get a new one. This is free — no x402 payment required. 
curl -X POST https://laso.finance/auth \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "AMf-vBx4N2..."}'
Response: 
{
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "AMf-vBx4N2...",
  "expires_in": "3600",
  "user_id": "0xabc..."
}
Store both the id_token and refresh_token. Use the id_token for requests, and when it expires, call POST /auth with the refresh_token to get a new pair. This way you only pay for GET /auth once.

​
Token lifecycle

┌─────────────────────────────────────────────────┐
│  GET /auth  ($0.001)                            │
│  or GET /get-card ($5-$1000)                    │
│         │                                       │
│         ▼                                       │
│  ┌─────────────┐                                │
│  │  id_token   │──── expires after ~1 hour ───┐ │
│  │refresh_token│                              │ │
│  └─────────────┘                              │ │
│         │                                     │ │
│         ▼                                     ▼ │
│  Use id_token as                     POST /auth  │
│  Bearer token for        (free, returns new pair)│
│  authenticated endpoints                        │
└─────────────────────────────────────────────────┘
If a human wants to see what their agent has been doing (cards, transactions, balances), use GET /get-auth-link to generate a one-time login URL: 
curl https://laso.finance/get-auth-link \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Response: 
{
  "auth_url": "https://laso.finance/?authToken=eyJ...",
  "user_id": "0xabc..."
}
Open auth_url in a browser to log in to the Laso Finance dashboard as that user. The link expires after a short time, so generate a new one if needed.

​
How wallet identity works

Your identity in the Laso Finance system is your wallet address:
  1. You call a paywalled endpoint with an x402 payment header
  2. The server extracts your wallet address from the payment header
  3. If it’s your first time, an account is created automatically
  4. Your user_id is your wallet address (lowercased)
  5. All tokens and cards are tied to this wallet address
This means there’s no separate signup or account creation — your wallet is your account.