> ## 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.

# Laso Finance API introduction and x402 overview

> Learn how the Laso Finance API uses the x402 protocol to gate endpoints behind USDC payments on Base and Solana for AI agents and clients.

## Overview

The Laso Finance API uses the [x402 protocol](https://www.x402.org/) to gate endpoints behind crypto payments on Base or Solana (USDC). Agents and clients can programmatically order USA and international prepaid cards, gift cards, and send money to USD, EUR, or GBP debit cards.

Sending money out to a bank account is a paywalled route like any other (`GET /send-bank-payment`), but the setup around it (opening the banking profile, registering who gets paid) is done through Firebase callables rather than paywalled routes, as is the [managed agent wallet](/guides/managed-agent-wallet). See [bank accounts](/guides/agent-bank-accounts) and [Beyond the x402 endpoints](#beyond-the-x402-endpoints).

## How x402 works

<Steps>
  <Step title="Call a paywalled endpoint">
    Make a request without a payment header. You'll receive a `402 Payment
            Required` response containing payment details (price, recipient address,
    network).
  </Step>

  <Step title="Construct a payment header">
    Use the details from the 402 response to create an x402 payment header with
    a Base or Solana USDC transaction.
  </Step>

  <Step title="Replay the request">
    Send the same request with the payment header attached. The server verifies
    the payment and processes your request.
  </Step>
</Steps>

An MPP client follows the same three steps: the 402 also carries a Machine Payments Protocol challenge in `WWW-Authenticate`, and the paid retry sends `Authorization: Payment ...` (USDC on Base) instead of a payment header. See [paying with MPP](/guides/how-x402-works#paying-with-mpp).

## Authentication

`GET /auth` is free: send a `SIGN-IN-WITH-X` header (a base64-encoded CAIP-122 signed message) to prove wallet ownership. The recommended way is `wrapFetchWithSIWx` from `@x402/extensions/sign-in-with-x`, which handles the full round-trip automatically. Paywalled endpoints (`/get-card`, `/order-gift-card`, `/get-push-to-card`, `/order-intl-card`, `/send-payment`) extract the payer's wallet address from the x402 payment header and also return auth credentials in their responses. No separate API key is needed.

The `/auth` and `/get-card` endpoints return auth credentials (`id_token`, `refresh_token`) that can be used as Bearer tokens for authenticated endpoints like `/get-card-data`. Always save these tokens so you can use the `id_token` for authenticated requests and the `refresh_token` to get a new token when it expires. The curl examples reference it as the `$LASO_ID_TOKEN` environment variable.

When the `id_token` expires, use `POST /auth` with `grant_type: "refresh_token"` to get a new one (free).

## Endpoints

| Endpoint | Method | Payment | Description |
| - | - | - | - |
| `/auth` | GET | Free (signature header) | Get API auth credentials. Send a `SIGN-IN-WITH-X` header (CAIP-122 wallet signature). |
| `/auth` | POST | Free | Refresh an expired ID token (`grant_type: "refresh_token"`) |
| `/get-card` | GET | \$5-\$1000 USDC | Order a USA prepaid card (U.S. only). Returns JSON by default (use `format=html` for browser redirect). |
| `/order-intl-card` | GET | \$100-\$1000 on-card (whole dollars) + 3.8% fee, less during a promotion | Order an international non-reloadable card. Admin fulfills the queued order within 24 hours. |
| `/cancel-intl-order` | POST | Free (Bearer token) | Cancel a queued international card order and refund the charged amount to account balance |
| `/get-card-data` | GET | Free (Bearer token) | Get card status and details for U.S. and international cards. Omit `card_id` to list all cards. |
| `/create-reloadable-card` | POST | Free (Bearer token) | Create a reloadable card from the account holder's balance with the card issuer. Reusable by default. |
| `/list-card-transactions` | GET | Free (Bearer token) | List transactions on the account holder's reloadable cards. |
| `/get-card-deposit-address` | GET | Free (Bearer token) | Get the holder's USDC deposit address at the card issuer, to fund a reloadable card balance (Base only). |
| `/get-card-issuer-status` | GET | Free (Bearer token) | Check the one-time card issuer link: `not_started`, `code_sent`, `linked`, or `kyc_required`. |
| `/start-card-issuer-link` | POST | Free (Bearer token) | Have the card issuer send the account holder a one-time code. The human enters it; never read their email. |
| `/verify-card-issuer-link` | POST | Free (Bearer token) | Complete the card issuer link with the code the account holder entered. |
| `/get-saved-cards` | GET | Free (Bearer token) | List the cards the holder saved themselves behind their passkey. No identity verification needed. |
| `/create-saved-card-link` | POST | Free (Bearer token) | Get a single-use link to send the holder, where they save a card they already own. |
| `/buy-with-saved-card` | POST | Free (Bearer token) | Shop online merchants in plain language and pay with the holder's saved card. The holder approves each order on their own device. |
| `/get-purchase-turn` | GET | Free (Bearer token) | Read a purchase turn that was still running. |
| `/get-purchase-conversation` | GET | Free (Bearer token) | Read a purchase conversation's orders and last checkout attempt. |
| `/get-account-balance` | GET | Free (Bearer token) | Laso account balance, plus the separate agent wallet balance under `agent_wallet` |
| `/withdraw` | POST | Free (Bearer token) | Withdraw USDC from the account balance to a Solana address you supply. Agent wallet funds move with `agentWalletTransfer` instead |
| `/get-withdrawal-status` | GET | Free (Bearer token) | Get withdrawal statuses |
| `/refresh-card-data` | POST | Free (Bearer token) | Trigger a card data refresh. For U.S. cards re-scrapes issuer; for international cards requests admin balance update. |
| `/search-gift-cards` | GET | Free (Bearer token) | Search and browse the gift card catalog |
| `/order-gift-card` | GET | \$5-\$9,000 USDC (face value converted to USD + fee) | Order a gift card from the catalog. `amount` is in the product's own currency, not USD. |
| `/get-push-to-card` | GET | Dynamic (USD/EUR/GBP face value + 4.8% fee, min 1.50) | Send money to a USD, EUR, or GBP debit card. Returns a URL to enter card details. |
| `/send-payment` | GET | Dynamic (\$5-\$1000 + 4.9% fee, min \$1.50) | Send a payment via Venmo or PayPal. Requires KYC on the calling wallet; otherwise returns a `kyc_url`. Payment is credited to account balance, so KYC-blocked sends are recoverable via `POST /withdraw`. |
| `/get-payment-status` | GET | Free (Bearer token) | Check the state of Venmo and PayPal payouts. Pass `payment_id` for one, `recipient_id` for one recipient's history, or neither for every payout sent. |
| `/payment-recipients` | GET | Free (Bearer token) | List the Venmo and PayPal recipients this account has paid before. Pay an entry's `handle` with `/send-payment`; manage the entry by its `recipient_id` with `POST` and `DELETE /payment-recipients`. |
| `/payment-recipients` | POST | Free (Bearer token) | Rename a saved recipient (`display_name`) or archive it (`archived: true`). Archiving keeps history and is reversible; prefer it over `DELETE`. |
| `/payment-recipients` | DELETE | Free (Bearer token) | Remove a saved recipient. Payment history is kept, but the removal is not reversible through the API. |
| `/fund-card-balance` | GET | Dynamic (\$5-\$10,000) | Load a reloadable card balance. Pay from Base or Solana; Laso bridges to your deposit address at the card issuer over CCTP. |
| `/withdraw-card-balance` | POST | Free (Bearer token) | Withdraw unspent money off a reloadable card: the card issuer pays USDC on Base to an address you supply, within 1-3 business days. |
| `/send-bank-payment` | GET | Dynamic (\$10-\$50,000 + 0.25% fee, min \$1.50) | Send dollars to a bank account by ACH. Needs a `destination_id` registered on an approved banking profile first. |
| `/bank-recipients` | GET | Free (Bearer token) | List your bank payout recipients and their `destination_id`s. |
| `/get-kyc-status` | GET | Free (Bearer token) | *Optional, only for KYC-gated features like `/send-payment`.* Check the wallet's verification status. |
| `/get-kyc-link` | GET | Free (Bearer token) | *Optional, only for KYC-gated features like `/send-payment`.* Get a link to complete identity verification. |
| `/register-webhook` | POST | Free (Bearer token) | Register an HTTPS URL to receive the account's notifications as signed POSTs (Standard Webhooks signatures). |
| `/get-webhook` | GET | Free (Bearer token) | Check the webhook registration and its delivery health. |
| `/delete-webhook` | POST | Free (Bearer token) | Remove the webhook registration. Other notification channels keep working. |
| `/get-auth-link` | GET | Free (Bearer token) | Get a login link for the web dashboard so a human can see agent activity |
| `/feedback` | POST | Free (Bearer token) | Send feedback about the API to the humans running Laso. Requires a completed real action; limited to 5/24h. |
| `/search-merchants` | GET | Free (Bearer token) | Search merchant spend data for the Non-Reloadable U.S. card |
| `/version` | GET | Free | Current content-hash version of the agent docs, also sent as the `X-Laso-Docs-Version` header on every response. Refetch the docs when it differs from the value you cached. |
| `/get-pricing` | GET | Free (no auth) | The fee schedule: fee rate, minimum fee, and amount limits for every paid product. |
| `/get-supported-countries` | GET | Free (no auth) | Where each product can be used or sent, as ISO country codes. |

### Polling for card details (required)

**IMPORTANT:** `/get-card` does NOT return the card number, CVV, or expiry — it only returns a `card_id` with `status: "pending"`. You MUST poll `/get-card-data` to retrieve the actual card details:

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

Poll every 2-3 seconds until `status` is `"ready"`, then read `card_details`.

## Beyond the x402 endpoints

Not everything an agent can do is a paywalled route. These are Firebase callables at `https://laso.finance/<name>`, authorized with the `id_token` from `/auth`, with arguments wrapped in a `data` object and replies in a `result` object.

### Bank accounts

An agent can open real banking rails for its account and read back the resulting bank details. It drives every step except identity verification, which the account owner must complete in person.

Paying someone is the one part that is a paywalled route rather than a callable: once a destination is registered, `GET /send-bank-payment` sends dollars to it and `GET /bank-recipients` lists what you can pay.

| Callable | Description |
| - | - |
| `createBankingProfile` | Open the banking profile. Returns `kycRequired` and a `kycUrl` to hand to your human when they have not verified yet. |
| `getBankingApplication` | Read what the application still needs: `ready`, `missingFields`, `applicationStatus`. |
| `updateBankingApplicationDetails` | Submit the non-identity application fields, such as employment status and source of funds. |
| `submitBankingApplication` | Submit for approval. Legal attestations are accepted on the owner's behalf. Safe to retry. |
| `getBankingProfileStatus` | Poll until approved. Lists per-rail capabilities and anything outstanding. |
| `createBankingAccount` | Open an `onramp` account (dollars in, USDC out) or an `offramp` account (USDC in, dollars out). Idempotent. |
| `listBankingAccounts` | Retrieve your own bank details: routing number, account number, bank name, or the off-ramp deposit address. |
| `createBankingRecipient`, `addBankingDestination`, `listBankingRecipients` | Register who gets paid and their bank account. `addBankingDestination` returns the `destination_id` that `GET /send-bank-payment` pays out to. |
| `getBankingTransaction`, `listBankingTransactions` | Follow a payment to settlement. Paying a destination is `GET /send-bank-payment`. |

<Card title="Bank accounts: give your agent real banking rails" icon="building-columns" href="/guides/agent-bank-accounts">
  Full walkthrough: the two account types, the application fields and their
  validation rules, and what the agent can and cannot do.
</Card>

### Managed agent wallet

| Callable | Description |
| - | - |
| `getAgentWallet` | Read the managed wallet's Solana address, USDC balance, and `needs_funding` flag. |
| `agentX402Pay` | Settle any x402 challenge from the wallet. Pass `route` for a Laso route, or `url` for any external endpoint with pinned price, network, and receiver. |
| `agentWalletTransfer` | Send USDC from the managed wallet to any Solana or Base address. |
| `getAgentSpendLimit` | Read the per-payment spend limit the account owner set, plus its bounds. Read-only to an agent. |

<Card title="Managed agent wallets" icon="wallet" href="/guides/managed-agent-wallet">
  Custody model, paying third-party x402 services under a per-call cap and an
  expected asset, network, and recipient, and how refusals and failed
  settlements are reported.
</Card>

## Discovery

Agents can discover this API via:

* **Agent skill file**: [laso.finance/SKILL.md](https://laso.finance/SKILL.md)
* **OpenAPI spec**: [laso.finance/openapi.json](https://laso.finance/openapi.json)
* **AI plugin manifest**: [laso.finance/.well-known/ai-plugin.json](https://laso.finance/.well-known/ai-plugin.json)
* **Agentic Resource Discovery manifest**: [laso.finance/.well-known/ai-catalog.json](https://laso.finance/.well-known/ai-catalog.json)
* **LLM context**: [laso.finance/llms.txt](https://laso.finance/llms.txt)
* **Docs version**: [laso.finance/.well-known/docs-version.json](https://laso.finance/.well-known/docs-version.json) and `GET /version` return the content-hash version of the agent docs. Refetch cached docs when it changes.

## Base URL

```
https://laso.finance
```


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