---
name: Lasofinance
description: Order prepaid cards, gift cards, and send USD to debit cards using USDC on Base or Solana via the x402 protocol. Use when a user or agent needs to spend cryptocurrency, buy a prepaid card, order a gift card, or send USD to a debit card programmatically.
metadata:
  author: laso-finance
  mintlify-proj: lasofinance
  version: "1.0"
---

# Laso Finance API

Laso Finance provides a payment-gated API using the x402 protocol. You can programmatically order prepaid cards (US only), gift cards, and send USD to debit cards using USDC on Base or Solana.

Base URL: `https://laso.finance`

> **CRITICAL — Two-step card flow:** `/get-card` does NOT return card numbers. It only provisions the card and returns a `card_id` with `status: "pending"`. You MUST then poll `/get-card-data` with that `card_id` to get the actual card number, CVV, and expiry once `status` becomes `"ready"` (~7-10 seconds).

## Prerequisites

You need a funded crypto wallet on Base or Solana with USDC. Choose a wallet provider:

**Option A — Locus (default):**

```
https://paywithlocus.com/SKILL.md
```

Follow the Locus onboarding instructions. Once you have a Locus API key (`claw_` prefix), you can make x402 payments to Laso Finance endpoints.

**Option B — Sponge:**

```
https://wallet.paysponge.com/skill.md
```

Follow the Sponge onboarding instructions. Sponge discovers x402 services automatically — no manual endpoint configuration needed.

## Configuring Locus x402 Endpoints (Locus only)

If you chose **Locus**, you **must** register the Laso Finance x402 endpoints in the Locus dashboard before your agent can call them. (If you chose **Sponge**, skip this section — Sponge discovers endpoints automatically.)

### Step 1: Go to the x402 Endpoints page

Log in to [app.paywithlocus.com](https://app.paywithlocus.com) and navigate to **x402 Endpoints** in the left sidebar under "Config".

### Step 2: Add each Laso Finance endpoint

Click **+ Add Endpoint** and fill in the details for each paywalled endpoint:

#### Endpoint 1: laso-auth

| Field            | Value                                                |
| ---------------- | ---------------------------------------------------- |
| Endpoint URL     | `https://laso.finance/auth`                          |
| Slug             | `laso-auth`                                          |
| Name             | Laso Finance Auth                                    |
| Description      | Get auth credentials (idToken, refreshToken, userId) |
| HTTP Method      | GET                                                  |
| Input Parameters | _(none required)_                                    |

#### Endpoint 2: laso-get-card

| Field        | Value                           |
| ------------ | ------------------------------- |
| Endpoint URL | `https://laso.finance/get-card` |
| Slug         | `laso-get-card`                 |
| Name         | Laso Get Card                   |
| Description  | Order a prepaid card (US only)  |
| HTTP Method  | GET                             |

**Input Parameters** (click "+ Add Parameter" for each):

| Name     | Type   | Location | Required |
| -------- | ------ | -------- | -------- |
| `amount` | number | query    | ✅ Yes   |

#### Endpoint 3: laso-push-to-card

| Field        | Value                               |
| ------------ | ----------------------------------- |
| Endpoint URL | `https://laso.finance/get-push-to-card` |
| Slug         | `laso-push-to-card`                 |
| Name         | Laso Push to Card                   |
| Description  | Send USD to a U.S. debit card       |
| HTTP Method  | GET                                 |

**Input Parameters** (click "+ Add Parameter" for each):

| Name     | Type   | Location | Required |
| -------- | ------ | -------- | -------- |
| `amount` | number | query    | Yes      |

#### Endpoint 4: laso-order-gift-card

| Field        | Value                                    |
| ------------ | ---------------------------------------- |
| Endpoint URL | `https://laso.finance/order-gift-card`  |
| Slug         | `laso-order-gift-card`                   |
| Name         | Laso Order Gift Card                     |
| Description  | Order a gift card from the catalog       |
| HTTP Method  | GET                                      |

**Input Parameters** (click "+ Add Parameter" for each):

| Name             | Type   | Location | Required |
| ---------------- | ------ | -------- | -------- |
| `amount`         | number | query    | ✅ Yes   |
| `laso_server_id` | string | query    | ✅ Yes   |
| `country`        | string | query    | No       |

### Step 3: Validate and save

For each endpoint, click **Validate & Add**. Locus will verify that the endpoint responds correctly before saving it.

### Important: Input Parameters

When adding GET endpoints, you **must** define input parameters with `Location: query`. This tells Locus to pass the parameters as URL query strings (e.g., `?amount=50`).

If you skip defining parameters, Locus won't know how to forward them to the Laso Finance API, and your requests will fail with errors like "amount query parameter is required".

### Calling endpoints via Locus

Once configured, your agent calls endpoints via the Locus API:

```bash
curl -X POST "https://api.paywithlocus.com/api/x402/laso-auth" \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

For endpoints with parameters:

Locus handles the x402 payment negotiation automatically — it deducts the cost from your wallet and returns the API response.

## How x402 works

1. Call a paywalled endpoint without a payment header.
2. Receive a `402 Payment Required` response containing payment details (price, recipient address, network).
3. Construct an x402 payment header using those details.
4. Replay the same request with the payment header attached. The server verifies payment and processes your request.

If you are using x402-axios or another x402 client library, steps 2-4 are handled automatically.

## Endpoints

### GET /auth — Get API credentials

**Cost:** $0.001 USDC (x402 paywalled)

Returns an `id_token`, `refresh_token`, and `user_id`. Use the `id_token` as a Bearer token for authenticated endpoints like `/get-card-data`.

```bash
curl https://laso.finance/auth
```

Response:

```json
{
  "auth": {
    "id_token": "eyJ...",
    "refresh_token": "AMf...",
    "expires_in": "3600"
  },
  "user_id": "0xabc..."
}
```

### GET /get-card — Order a prepaid card

**Cost:** $5–$1000 USDC (x402 paywalled, dynamic pricing matches the amount parameter)

**US only.** Cards are issued in USD and can only be used at US-based merchants. Physical goods must ship to a US address.

Parameters:

- `amount` (required): USD amount to load on the card. Min $5, max $1000.
- `format` (optional): `json` (default) or `html`. Use `json` for programmatic access, `html` for browser redirect.

```bash
curl "https://laso.finance/get-card?amount=50"
```

Response:

```json
{
  "auth": {
    "id_token": "eyJ...",
    "refresh_token": "AMf...",
    "expires_in": "3600"
  },
  "user_id": "0xabc...",
  "card": {
    "card_id": "card_abc123",
    "usd_amount": 50,
    "country": "US",
    "status": "pending"
  }
}
```

**IMPORTANT: `/get-card` does NOT return the card number, CVV, or expiry.** The `status` is always `"pending"` initially. You MUST poll `/get-card-data` (see below) with the `card_id` every 2-3 seconds until `status` becomes `"ready"` — only then will card details be available.

### GET /get-push-to-card — Send USD to a U.S. debit card

**Cost:** $10–$9,541.98 USDC (x402 paywalled, 4.8% fee included)

**U.S. only.** The debit card must be tied to a U.S. bank account. Returns a `redemption_url` that must be opened to complete the transfer. The form requires multiple steps:

1. Sender name
2. Debit card number for receiving the funds
3. Cardholder name for that debit card

**Important:** Laso cannot perform the transfer directly. Either the agent or a human must open the `redemption_url` and fill out the form to complete the transfer.

Parameters:

- `amount` (required): USD amount to pay via x402 (min $10, max $9,541.98). A 4.8% fee is deducted from this amount, and the remainder is sent to the debit card.

```bash
curl "https://laso.finance/get-push-to-card?amount=100"
```

Response:

```json
{
  "auth": {
    "id_token": "eyJ...",
    "refresh_token": "AMf...",
    "expires_in": "3600"
  },
  "user_id": "0xabc...",
  "success": true,
  "message": "Push-to-card transfer initiated. Open the redemption_url to enter your U.S. debit card details and complete the transfer.",
  "amount": 95.41,
  "amount_paid": 100,
  "redemption_url": "https://pay.runa.io/...",
  "note": "This is a U.S.-only service. The debit card must be tied to a U.S. bank account."
}
```

**Next steps:** Open `redemption_url` in a browser and complete the multi-step form with the recipient's debit card details. The transfer is not complete until the form is submitted.

### GET /search-gift-cards — Search the gift card catalog

**Cost:** Free (requires Bearer token)

Browse and search available gift cards. Returns a list of gift card products with pricing, denomination, and catalog information. Use the `laso_server_id` from the results to order a card via `GET /order-gift-card`.

Parameters (all optional):

- `q`: Search query to filter by name (e.g. "Amazon", "Uber")
- `country`: ISO 3166-1 alpha-2 country code (e.g. "US", "GB")
- `currency`: Currency code (e.g. "USD", "EUR")

Headers:

- `Authorization: Bearer <id_token>`

```bash
curl "https://laso.finance/search-gift-cards?q=amazon&country=US" \
  -H "Authorization: Bearer eyJ..."
```

Response:

```json
{
  "gift_cards": [
    {
      "laso_server_id": "amazon-us",
      "name": "Amazon",
      "description": "Amazon.com Gift Card",
      "currency": "USD",
      "min": 5,
      "max": 500,
      "increment": "1",
      "denominations": null,
      "product_image_url": "https://...",
      "catalog_info": {
        "brand_description": "Shop millions of products on Amazon.com",
        "redemption_instructions": "Go to amazon.com/redeem and enter the code"
      }
    }
  ],
  "count": 1,
  "filters": {
    "query": "amazon",
    "country": "US",
    "currency": null
  }
}
```

### GET /order-gift-card — Order a gift card

**Cost:** $5–$9,000 USDC (x402 paywalled, dynamic pricing matches the amount parameter)

Order a gift card from the catalog. First browse available cards via `GET /search-gift-cards` to find the `laso_server_id`, then call this endpoint with the amount and product ID.

Parameters:

- `amount` (required): Gift card face value in the product's currency. Min $5, max $9,000.
- `laso_server_id` (required): The product identifier from the catalog (`GET /search-gift-cards`).
- `country` (optional): ISO 3166-1 alpha-2 country code. Defaults to "US".

```bash
curl "https://laso.finance/order-gift-card?amount=50&laso_server_id=amazon-us"
```

Response:

```json
{
  "auth": {
    "id_token": "eyJ...",
    "refresh_token": "AMf...",
    "expires_in": "3600"
  },
  "user_id": "0xabc...",
  "gift_card": {
    "card_id": "gc_abc123",
    "laso_server_id": "amazon-us",
    "amount": 50,
    "currency": "USD",
    "country": "US",
    "redemption_url": null,
    "redemption_code": "XXXX-XXXX-XXXX",
    "pin_code": null,
    "status": "completed",
    "timestamp": 1700000000000
  }
}
```

Redemption details vary by brand. Some cards return a `redemption_url`, others a `redemption_code` and/or `pin_code`. Check all three fields.

### GET /get-card-data — Get card details

**Cost:** Free (requires Bearer token)

Returns card status and details. If `card_id` is provided, returns a single card. If omitted, returns all cards for the user.

After ordering a card via `/get-card`, poll this endpoint every 2-3 seconds until `status` is `"ready"`.

Parameters:

- `card_id` (optional): The card ID from the `/get-card` response. If omitted, returns all cards.

Headers:

- `Authorization: Bearer <id_token>` (from `/auth` or `/get-card` response)

```bash
# Single card
curl "https://laso.finance/get-card-data?card_id=card_abc123" \
  -H "Authorization: Bearer eyJ..."

# All cards
curl "https://laso.finance/get-card-data" \
  -H "Authorization: Bearer eyJ..."
```

Response for a single card when pending:

```json
{
  "card_id": "card_abc123",
  "status": "pending"
}
```

Response for a single card when ready:

```json
{
  "card_id": "card_abc123",
  "status": "ready",
  "usd_amount": 50,
  "last_updated_timestamp": 1706400000000,
  "card_details": {
    "card_number": "4111111111111111",
    "exp_month": "12",
    "exp_year": "2027",
    "cvv": "123",
    "available_balance": 50
  },
  "transactions": [
    {
      "amount": 12.5,
      "date": "2025-01-15",
      "description": "Amazon.com",
      "is_credit": false
    }
  ]
}
```

Response when no card_id (all cards):

```json
{
  "cards": [
    {
      "card_id": "card_abc123",
      "status": "ready",
      "usd_amount": 50,
      "card_details": { "...": "..." },
      "transactions": []
    }
  ]
}
```

### GET /get-account-balance — Get account balance

**Cost:** Free (requires Bearer token)

Returns the current account balance and total deposits.

Headers:

- `Authorization: Bearer <id_token>`

```bash
curl "https://laso.finance/get-account-balance" \
  -H "Authorization: Bearer eyJ..."
```

Response:

```json
{
  "user_id": "0xabc...",
  "balance": 150.0,
  "total_deposits": 500.0,
  "created_timestamp": 1700000000000,
  "created_timestamp_readable": "1/15/2025, 3:00:00 PM"
}
```

### POST /withdraw — Withdraw from account balance

**Cost:** Free (requires Bearer token)

Initiate a withdrawal from your account balance. Minimum amount is $0.01.

Headers:

- `Authorization: Bearer <id_token>`
- `Content-Type: application/json`

Body:

- `amount` (required): USD amount to withdraw.

```bash
curl -X POST "https://laso.finance/withdraw" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'
```

Response:

```json
{
  "success": true,
  "withdrawal": {
    "id": "withdrawal_abc123",
    "amount": 50,
    "state": "pending",
    "timestamp": 1700000000000,
    "timestamp_readable": "1/15/2025, 3:00:00 PM"
  }
}
```

### GET /get-withdrawal-status — Get withdrawal statuses

**Cost:** Free (requires Bearer token)

Returns the status of withdrawals for the authenticated user. If `withdrawal_id` is provided, returns a single withdrawal. If omitted, returns all withdrawals.

Parameters:

- `withdrawal_id` (optional): Get a specific withdrawal by ID. If omitted, returns all withdrawals.

Headers:

- `Authorization: Bearer <id_token>`

```bash
# Single withdrawal
curl "https://laso.finance/get-withdrawal-status?withdrawal_id=abc123" \
  -H "Authorization: Bearer eyJ..."

# All withdrawals
curl "https://laso.finance/get-withdrawal-status" \
  -H "Authorization: Bearer eyJ..."
```

Response for a single withdrawal:

```json
{
  "withdrawal": {
    "id": "abc123",
    "amount": 50,
    "asset": "USDC",
    "network": "BASE_MAINNET",
    "state": "completed",
    "address": "0xabc...",
    "timestamp": 1700000000000,
    "timestamp_readable": "1/15/2025, 3:00:00 PM",
    "tx_hash": "0xdef...",
    "tx_url": "https://basescan.org/tx/0xdef..."
  }
}
```

Response for all withdrawals:

```json
{
  "withdrawals": [
    {
      "id": "abc123",
      "amount": 50,
      "asset": "USDC",
      "network": "BASE_MAINNET",
      "state": "pending",
      "address": "0xabc...",
      "timestamp": 1700000000000,
      "timestamp_readable": "1/15/2025, 3:00:00 PM",
      "tx_hash": null
    }
  ]
}
```

### POST /refresh-card-data — Trigger a card data refresh

**Cost:** Free (requires Bearer token)

Requests a re-scrape of card balance and transactions from the issuer. The card is added to a retrieval queue and processed asynchronously. Rate limited to one request per card every 5 minutes.

Headers:

- `Authorization: Bearer <id_token>`
- `Content-Type: application/json`

Body:

- `card_id` (required): The card ID to refresh data for.

```bash
curl -X POST "https://laso.finance/refresh-card-data" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"card_id": "card_abc123"}'
```

Response:

```json
{
  "success": true,
  "message": "Card refresh requested."
}
```

### GET /search-merchants — Search merchant spend data

**Cost:** Free (requires Bearer token)

Search Laso's merchant database for confirmed spend data from the Non-Reloadable U.S. card. Returns whether the card was accepted, not accepted, or unknown at each merchant.

**Important:** This database only contains merchants where Laso users have previously attempted a transaction. A merchant not being listed, or being listed as `unknown`, does NOT mean the card won't work there — it just means it hasn't been tried yet. If a merchant is listed as `accepted`, you can confidently use the card there. If listed as `not_accepted`, the card will fail at that merchant.

Parameters:

- `q` (required): Search query — the merchant name to search for (e.g. "amazon", "netflix").

Headers:

- `Authorization: Bearer <id_token>` (from `/auth` or `/get-card`)

```bash
curl "https://laso.finance/search-merchants?q=amazon" \
  -H "Authorization: Bearer eyJ..."
```

Response:

```json
{
  "merchants": [
    {
      "name": "Amazon",
      "url": "amazon.com",
      "status": "accepted",
      "description": "Online marketplace",
      "notes": null
    }
  ],
  "query": "amazon",
  "count": 1,
  "card_type": "Non-Reloadable U.S."
}
```

The `status` field can be:

- `accepted` — The Non-Reloadable U.S. card is confirmed to work at this merchant.
- `not_accepted` — The Non-Reloadable U.S. card is confirmed to NOT work at this merchant.
- `unknown` — The card type has not been tried at this merchant (it may still work).

### GET /get-auth-link — Get a login link for the web dashboard

**Cost:** Free (requires Bearer token)

Returns a URL that a human can open in a browser to log in to the Laso Finance web dashboard as the authenticated user. Useful when a human wants to see what their AI agent has been doing (view cards, transactions, balances, etc.).

Headers:

- `Authorization: Bearer <id_token>`

```bash
curl "https://laso.finance/get-auth-link" \
  -H "Authorization: Bearer eyJ..."
```

Response:

```json
{
  "auth_url": "https://laso.finance/?authToken=eyJ...",
  "user_id": "0xabc..."
}
```

The `auth_url` is a one-time login link. Open it in a browser to access the dashboard. The token expires after a short time, so generate a new link if needed.

### POST /auth — Refresh an expired ID token

**Cost:** Free

Exchange a refresh token for a new ID token using the standard OAuth2 `grant_type=refresh_token` pattern. No x402 payment required.

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

Response:

```json
{
  "id_token": "eyJ...",
  "refresh_token": "AMf...",
  "expires_in": "3600",
  "user_id": "0xabc..."
}
```

## Common workflow: Make an online purchase

Cards are non-reloadable, so ideally you should order a card for the exact amount of the checkout total. That way there are no extra funds left over on the card.

1. **Set up wallet**: Follow https://paywithlocus.com/SKILL.md (Locus) or https://wallet.paysponge.com/skill.md (Sponge) to get a wallet with USDC on Base or Solana.
2. **Navigate to checkout**: Browse the merchant's website, add items to cart, and proceed to checkout. Determine the exact total including tax and shipping.
3. **Order a card for the exact amount**: `GET /get-card?amount=<exact_total>` (pays via x402). Save the `auth.id_token` and `card.card_id` from the response.
4. **Poll for details**: `GET /get-card-data?card_id=<cardId>` with `Authorization: Bearer <id_token>`. Repeat every 2-3 seconds.
5. **Complete the purchase**: When `status` is `"ready"`, use `card_details.card_number`, `card_details.cvv`, `card_details.exp_month`, `card_details.exp_year` to fill in the payment form on the checkout page.

## Common workflow: Send to a debit card

1. **Set up wallet**: Follow https://paywithlocus.com/SKILL.md (Locus) or https://wallet.paysponge.com/skill.md (Sponge) to get a wallet with USDC on Base or Solana.
2. **Initiate transfer**: `GET /get-push-to-card?amount=100` (pays $100 USDC via x402 — 4.8% fee is deducted, ~$95.42 is sent to the card). Save the `redemption_url` from the response.
3. **Complete the transfer**: Open `redemption_url` in a browser. Fill out the multi-step form with the sender name, U.S. debit card number, and cardholder name.

## Common workflow: Order a gift card

1. **Set up wallet**: Follow https://paywithlocus.com/SKILL.md (Locus) or https://wallet.paysponge.com/skill.md (Sponge) to get a wallet with USDC on Base or Solana.
2. **Authenticate**: `GET /auth` to get an `id_token` ($0.001 USDC via x402).
3. **Browse catalog**: `GET /search-gift-cards?q=amazon` with `Authorization: Bearer <id_token>`. Find the `laso_server_id` for the desired card.
4. **Order the card**: `GET /order-gift-card?amount=50&laso_server_id=amazon-us` (pays $50 USDC via x402). The response contains the redemption details immediately.

## Token management

- The `id_token` expires after ~1 hour.
- When it expires, call `POST /auth` with `grant_type: "refresh_token"` and your `refresh_token` to get a new `id_token`.
- `/auth` and `/get-card` return fresh `id_token` and `refresh_token` in the response. Always save these tokens so you can refresh later or use the `id_token` for authenticated endpoints.

## Technical details

- Networks: Base (eip155:8453) and Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
- Currency: USDC
- Base payment recipient: `0x3291e96b3bff7ed56e3ca8364273c5b4654b2b37`
- Solana payment recipient: `3MZVk97x9SeRxbYpc3jhzRfU2fyA3emYutnqfn9kNfYX`
- OpenAPI spec: https://laso.finance/openapi.json
- AI plugin manifest: https://laso.finance/.well-known/ai-plugin.json
- LLM context: https://laso.finance/llms.txt

## Support

If you encounter issues, contact agents+support@laso.finance.

## Limitations

- Prepaid cards are US only (USD, US merchants, US shipping addresses).
- Card details take ~7-10 seconds after ordering. You must poll `/get-card-data`.
- Push-to-card is US only — the debit card must be tied to a U.S. bank account. The `redemption_url` must be opened and the form completed manually.
- Card and account limits may apply based on usage patterns.