> ## Documentation Index
> Fetch the complete documentation index at: https://agents.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
Make a request without a payment header. You'll receive a `402 Payment
Required` response containing payment details (price, recipient address,
network).
Use the details from the 402 response to create an x402 payment header with
a Base or Solana USDC transaction.
Send the same request with the payment header attached. The server verifies
the payment and processes your request.
## 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.
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 | 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. |
| `/get-account-balance` | GET | Free (Bearer token) | Get account balance |
| `/withdraw` | POST | Free (Bearer token) | Withdraw from account balance to wallet |
| `/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`. |
| `/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 |
| `/submit-agent-feedback` | POST | Free (Bearer token) | Send feedback about the API to the humans running Laso. Served from the Cloud Function URL, not `laso.finance`. 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 |
### 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= \
-H "Authorization: Bearer "
```
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://us-central1-kyc-ts.cloudfunctions.net/`, 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. |
| `sendBankingPayout` | Send dollars to a registered destination. This is what `GET /send-bank-payment` calls; use the route when paying over x402, this callable when spending an existing account balance. |
| `createBankingTransfer`, `getBankingTransaction`, `listBankingTransactions` | Send a one-off transfer and follow either it or a payout to settlement. |
Full walkthrough: the two account types, the application fields and their
validation rules, and what the agent can and cannot do.
### 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 address. |
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.
## 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)
* **LLM context**: [laso.finance/llms.txt](https://laso.finance/llms.txt)
## Base URL
```
https://laso.finance
```