> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laso.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and bearer tokens in Laso Finance

> Learn how the Laso Finance API authenticates requests using SIGN-IN-WITH-X wallet signatures, x402 payment headers, and OAuth2 bearer tokens.

## Overview

The Laso Finance API uses three authentication mechanisms:

1. **`SIGN-IN-WITH-X` header** for `GET /auth`. A base64-encoded CAIP-122 signed message that proves wallet ownership. Free.
2. **`x-payment` header** on the paywalled endpoints (`/get-card`, `/order-gift-card`, `/get-push-to-card`, `/order-intl-card`, `/send-payment`, `/send-bank-payment`). The signed x402 payment payload. The server verifies it, settles the payment, and extracts the payer's wallet address. An MPP client sends its credential as `Authorization: Payment ...` instead; the payer's wallet is extracted the same way.
3. **Bearer tokens**. For authenticated endpoints like `/get-card-data`, `/get-account-balance`, etc. Pass an `id_token` as a `Bearer` token in the `Authorization` header.

## Getting tokens

Call `GET /auth` (free) or `GET /get-card` (which costs the card amount in USDC) to receive auth credentials:

```json theme={null}
{
  "auth": {
    "id_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "AMf-vBx4N2...",
    "expires_in": "3600"
  },
  "user_id": "0xabc123..."
}
```

| Field | Description |
| - | - |
| `id_token` | Firebase ID token. Use as `Bearer` token for authenticated endpoints. Expires after \~1 hour. |
| `refresh_token` | Long-lived token for getting new `id_token`s. |
| `expires_in` | Token lifetime in seconds (typically 3600 = 1 hour). |
| `user_id` | Your user ID, derived from your wallet address (lowercased). |

### Signing in with SIGN-IN-WITH-X

Build a CAIP-122 message and sign it with your wallet, then send it base64-encoded in the `SIGN-IN-WITH-X` header. The `@x402/extensions/sign-in-with-x` package handles the construction and the `wrapFetchWithSIWx` helper handles the full request flow automatically:

```typescript theme={null}
import { wrapFetchWithSIWx } from "@x402/extensions/sign-in-with-x";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const fetchWithSiwx = wrapFetchWithSIWx(fetch, signer);

const res = await fetchWithSiwx("https://laso.finance/auth");
const { auth, user_id } = await res.json();
```

The server-side validation enforces:

* Domain binding: the signed message's `domain` must match `laso.finance`.
* Nonce uniqueness: each signature can only be used once.
* 5-minute expiry: signatures older than 5 minutes are rejected.

A rejected signature returns **402 Payment Required** (not 401), the same response as a request with no credentials at all. This follows the x402 protocol: the 402 carries a fresh challenge (new nonce, payment options, SIWX info) base64-encoded in the `PAYMENT-REQUIRED` response header, so the correct recovery is to sign the new challenge and retry. If you receive a 402 after sending a `SIGN-IN-WITH-X` header, treat it as a verification failure. Do not resend the same payload.

Supported chains:

| `chainId` | Type |
| - | - |
| `eip155:8453` (Base) | `eip191` (EOA) |
| `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (mainnet) | `ed25519` |

## Using tokens

Pass the `id_token` as a Bearer token in the `Authorization` header (the examples write it as `$LASO_ID_TOKEN`, exported from your saved credentials):

```bash theme={null}
curl https://laso.finance/get-card-data?card_id=O-01ABC123 \
  -H "Authorization: Bearer $LASO_ID_TOKEN"
```

## Refreshing tokens

### Why tokens expire

The `id_token` returned by `/auth` and `/get-card` expires after approximately **1 hour** (3600 seconds). After expiry, authenticated endpoints like `/get-card-data` return `401 Unauthorized`.

The `refresh_token` is long-lived and can be used to get a new `id_token` without paying again.

### Refreshing a token

Call `POST /auth` with `grant_type: "refresh_token"` and your `refresh_token`. This follows the standard OAuth2 pattern and is free: no x402 payment required.

```bash theme={null}
curl -X POST https://laso.finance/auth \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "AMf-vBx4N2..."}'
```

Response:

```json theme={null}
{
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "AMf-vBx4N2...",
  "expires_in": "3600",
  "user_id": "0xabc..."
}
```

> [!NOTE]
>
> The response returns a new `refresh_token` as well. Always store the latest
> `refresh_token` from each response.

### Proactive refresh

Don't wait for a `401` error. Refresh the token before it expires:

```typescript theme={null}
const TOKEN_LIFETIME_MS = 3600 * 1000; // 1 hour
const REFRESH_BUFFER_MS = 5 * 60 * 1000; // 5 minutes before expiry

let tokenIssuedAt = Date.now();

function shouldRefresh() {
  return Date.now() - tokenIssuedAt > TOKEN_LIFETIME_MS - REFRESH_BUFFER_MS;
}

async function getValidToken() {
  if (shouldRefresh()) {
    const { data } = await axios.post("https://laso.finance/auth", {
      grant_type: "refresh_token",
      refresh_token: currentRefreshToken,
    });
    currentIdToken = data.id_token;
    currentRefreshToken = data.refresh_token;
    tokenIssuedAt = Date.now();
  }
  return currentIdToken;
}
```

### Reactive refresh

Alternatively, catch `401` errors and refresh on demand:

```typescript theme={null}
async function callWithRefresh(requestFn) {
  try {
    return await requestFn(currentIdToken);
  } catch (error) {
    if (error.response?.status === 401) {
      const { data } = await axios.post("https://laso.finance/auth", {
        grant_type: "refresh_token",
        refresh_token: currentRefreshToken,
      });
      currentIdToken = data.id_token;
      currentRefreshToken = data.refresh_token;
      return await requestFn(currentIdToken);
    }
    throw error;
  }
}
```

### Store both tokens

Always persist both the `id_token` and `refresh_token`. If you lose the `refresh_token`, you'll need to call `GET /auth` again, which is free but requires signing a fresh `SIGN-IN-WITH-X` message.

> [!TIP]
>
> You only need to hit `GET /auth` once per session. Use the `id_token` for requests, and when it expires, call `POST /auth` with the `refresh_token` to get a new pair.

### Error responses

| Status | Meaning |
| - | - |
| `200` | Success, new tokens returned |
| `400` | Invalid or missing `grant_type` or `refresh_token` in request body |
| `401` | Token is invalid or revoked, so you must re-authenticate via `/auth` |

## Token lifecycle

```
┌─────────────────────────────────────────────────┐
│  GET /auth  (free, SIGN-IN-WITH-X header)       │
│  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                        │
└─────────────────────────────────────────────────┘
```

## Getting a login link for humans

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:

```bash theme={null}
curl https://laso.finance/get-auth-link \
  -H "Authorization: Bearer $LASO_ID_TOKEN"
```

Response:

```json theme={null}
{
  "auth_url": "https://laso.finance/agent/dashboard/auth?code=K7MPQ-W3XZ9",
  "user_id": "0xabc...",
  "expires_in": 900
}
```

Give `auth_url` to the human exactly as received; opening it in a browser logs them in to the Laso Finance dashboard as that user. The URL carries a short single-use login code rather than a long token, so it passes through tool-output credential filters intact. Agents should not fetch or open it themselves, since redeeming the code consumes the human's login. The code expires after 15 minutes, so generate a new link if needed.

## How wallet identity works

Your identity in the Laso Finance system is your wallet address:

1. You call `GET /auth` with a `SIGN-IN-WITH-X` header.
2. The server cryptographically verifies the signature and extracts your wallet address.
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.