How to connect Laso MCP with Python

Get the current docs version Returns the current API contract version (`api_version`), the versioning and deprecation policy, and the content-hash version of the Laso Finance agent docs (`SKILL.md`, `openapi.json`, `llms.txt`, `llms-full.txt`, `ai-plugin.json`). Free, no auth or payment header. Agents aggressively cache these docs, so use this to detect a stale cache: if the `docs_version` you last saw differs from the value returned here, refetch the docs. Every API response also carries this value in the `X-Laso-Docs-Version` response header, alongside `X-Laso-Docs-Manifest`, which points at the authoritative freshness beacon at `https://laso.finance/.well-known/docs-version.json`. This route is also the `status` target of the API catalog at `https://laso.finance/.well-known/api-catalog` (RFC 9727), which every response advertises via a `Link` header with `rel="api-catalog"`.

Refresh an ID token Exchange a refresh token for a new ID token. This is a free endpoint — no x402 payment required. Uses the standard OAuth2 `grant_type=refresh_token` pattern.

Order a USA prepaid card Pay between $5–$1000 USDC to order a Laso Finance USA prepaid card. By default returns JSON with auth credentials and card info (for AI agents). Pass `format=html` to get an HTML redirect to the card redemption URL (for browser-based flows). The JSON response includes a `card.status` of `"pending"`. Card details (number, CVV, etc.) take ~7-10 seconds to become available. Poll `getCardData` at the `callableBaseUrl` to check when `status` becomes `"ready"`. **U.S. only.** This card is issued in USD and can only be used for purchases at U.S.-based merchants. Physical goods must ship to a U.S. address. For non-U.S. merchants or non-USD currencies, use `GET /order-intl-card` instead. This endpoint is intended for the caller's own use — the card is non-transferable. PAID ROUTE (5-1000 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Get card details Returns the current status and details of card orders. If `card_id` is provided, returns a single card, looked up across U.S. non-reloadable, international non-reloadable, and reloadable cards. If omitted, returns all cards of the given `card_type` for the authenticated user; `card_type` defaults to `Non-Reloadable U.S.` when omitted, so existing callers see unchanged behavior. Pass `card_type=Non-Reloadable International` to list international cards, or `card_type=Reloadable` to list reloadable cards. For U.S. non-reloadable cards, details take ~7-10 seconds to become available after ordering; poll every 2-3 seconds until `status` is `"ready"`, then read `card_details`. For international non-reloadable cards, the order is `queued` until an admin fulfills it (typically within 24 hours), after which `card_details` is populated. For international cards, the `card_id` returned by `/order-intl-card` is a queue id. After admin fulfillment, the issuer's transaction id becomes the new `card_id` and the original queue id is preserved on the card as `queued_order_card_id`. You can keep polling `/get-card-data?card_id=<original-queue-id>` and it will resolve to the fulfilled card. **Reloadable cards** are a separate product, set up by the account holder in the Laso dashboard rather than ordered through this API. They are reusable (a `multi_use` card stays open across charges until its limit is spent) and can be topped up, unlike the single-load non-reloadable cards. Listing them returns `balance`, `spend_limit`, `last4`, `expiry`, and `reusable`. If the wallet has no card issuer account linked, the list is empty and a `note` explains how the holder sets one up. Reading a reloadable card's **number and CVV** is gated by the card issuer, and which gate applies depends on who issued it. Request the card by `card_id`; the response carries exactly one of three fields. `card_details` is the normal result for a card created through `/create-reloadable-card`, which Laso issues on the holder's behalf and can read for them directly — no approval step is involved. `details_approval` with `status: "pending"` and an `approval_id` appears only for a card the holder created in a DIFFERENT app: the issuer has emailed them an approve/deny link, and once they approve you retry as `GET /get-card-data?card_id=<CARD_ID>&approval_id=<APPROVAL_ID>` to receive `card_details`. `details_error` means the issuer could not return the number; retry shortly, and if it persists the holder can read the card in the dashboard. Spend the card by entering its number, expiry, and CVV at the merchant's checkout. `billing_address` is null on these cards and always will be — the issuer holds no billing address for a card. If a merchant requires one, use the address the account holder gave at identity verification (ask them; do not guess), since these cards are AVS-checked against it and a mismatch is the most common decline on a card that has funds. A card with `reusable: true` stays open after an approved charge and can be spent again up to its remaining `balance`; a charge larger than the balance is declined in full, as there are no partial approvals.

List reloadable card transactions Returns transactions on the authenticated user's **reloadable** cards, newest first: amount, merchant, status, and timestamps. Pass `card_id` for one card's history, or omit it for every reloadable card on the account. Filter with `status` and cap the page with `limit`. This route covers reloadable cards only. The two non-reloadable products keep their history in Laso's own records and are read through `/get-card-data`. If the wallet has no card issuer account linked, the list is empty and a `note` explains how the account holder sets one up at https://laso.finance/agent/dashboard/verified/card.

Get the reloadable card deposit address Returns the account holder's own USDC deposit address at the card issuer, and the balance currently on it. **This is how an agent funds a reloadable card balance with crypto.** Funding is user-funded: the address belongs to the account holder, so USDC sent to it credits their balance and funds their cards. The issuer provisions the address on first read, so simply calling this creates it. **Base only.** The address takes USDC on Base. USDC sent on another chain is unrecoverable. A Laso managed agent wallet holds USDC on **Solana**, so fund from a wallet that holds USDC on Base rather than transferring straight from a managed wallet. Deposits usually confirm within a couple of minutes. Poll this endpoint until `balance` reflects the deposit, then call `POST /create-reloadable-card`. The address is stable per holder, but read it through this endpoint rather than caching it: the issuer is the only authority on it.

List the holder's saved cards Lists the cards the account holder saved themselves: a card they already own, typed once on the card issuer's page and locked behind their passkey. **Nothing is issued or prefunded, and no identity verification is needed.** Every purchase paid with a saved card is approved by the holder on their own device. The response carries display fields only, never a card number. An empty `cards` list means nothing is saved yet: call `POST /create-saved-card-link` and send the returned `url` to your human.

Get a link for the holder to save their own card Returns a single-use link where the account holder types a card they already own and locks it with their passkey. The card is encrypted on their device; Laso never sees the number. **Send the `url` to your human. Do not open it yourself.** Saving a card is the holder's step, like identity verification: the page asks for the card and a passkey, with no account to create and no code to type. Poll `GET /get-saved-cards` until the card appears. Each link works once and expires at `expires_at`; mint a new one if it lapses. **This route is free** and needs no identity verification or prior setup: the holder's first saved card creates their card account.

Shop and pay with the holder's saved card Buys from online merchants (Amazon, Walmart, Target, Best Buy, DoorDash and more) and pays with the card the account holder saved themselves (see `GET /get-saved-cards`). One conversation per purchase: 1. Send what to buy as `ask`, in plain language. Pass `delivery_address` on this first call when you know it. 2. Relay `reply` to the holder and send their answers back as `ask` with the same `conversation_id`, until a `cart` comes back. 3. Show the holder the cart. Once they agree, send its `hash` as `confirm` with the `conversation_id`. Nothing can be charged before this. 4. The confirm answers `awaiting_approval` with an `approval_url`. **Send it to your human; never open it yourself.** They approve on their own device with their passkey. Then send the same confirm again to get `order_placed`. A turn runs against a live merchant and can take up to two minutes. This call waits about 45 seconds: a turn that finishes in time comes back complete (`state: done`); a slower one comes back as `state: running` with a `turn_id` to poll with `GET /get-purchase-turn`. **This route is free.** The holder's own card pays the merchant, and no identity verification is needed.

Read a purchase turn that was still running Reads back a turn from `POST /buy-with-saved-card` that came back `state: running`. Poll every few seconds until `state` is `done` or `failed`; the response has the same shape as the POST. A `failed` confirm may still have placed the order. Read `GET /get-purchase-conversation` before sending it again.

Read a purchase conversation's orders The record of a purchase conversation: whether a turn is still running, the last checkout attempt, and every order it placed with its charge status. Use it to track an order, and to settle what happened before repeating a confirm whose outcome is unclear (`in_progress`, `charge_status: unknown`, or a `failed` turn).

Create a reloadable card Creates a **reloadable** card funded from the account holder's balance with the card issuer, and returns it. This is the same card the holder creates in the Laso dashboard, so an agent and a human end up with the same product. The card is **reusable by default** (`reusable: true`): it stays open across charges until its limit is spent. Pass `reusable: false` for a single-use card that closes after its first approved charge. **This route is free** — no x402 payment. The card draws on the account holder's own balance with the issuer, so Laso fronts nothing. **If the balance is short**, this route answers `402`. Fund it by sending USDC: `GET /get-card-deposit-address` returns the holder's own deposit address at the card issuer (USDC on Base only), and the balance credits within a couple of minutes. The holder can also top up with Apple or Google Pay in the dashboard. Read the new card's number and CVV with `/get-card-data?card_id=...`. A card created here is Laso-issued, so its `card_details` come back directly — the approval step applies only to cards the holder created in a different app.

Get account balance Returns the current account balance and total deposits for the authenticated user.

Get KYC verification status (optional) **KYC is optional.** Most endpoints (cards, gift cards, push-to-card, account balance, withdrawals) do not require verification. It is only needed for certain features such as Venmo/PayPal payouts via `/send-payment`, and may be used for additional controls in the future. If you are not using those features, you can ignore the verification endpoints entirely. Returns the calling wallet's cached KYC verification status. Use this as a free pre-flight check before paying for `/send-payment`: if `kyc_verified` is `true` the payout will go through. If it is `false`, don't call `/send-payment` yet — that call would not send the payout (it returns `kyc_required` and a `kyc_url`), and the USDC you paid would just land in your account balance, recoverable with `POST /withdraw`. To start verification when not verified, call `/get-kyc-link`. This reads the cached status kept up to date by the verification webhook; it does not start verification or return a verification link.

Get a KYC verification link (optional) **KYC is optional.** It is only needed for certain features such as Venmo/PayPal payouts via `/send-payment`, and may be used for additional controls in the future. If you are not using those features, you can ignore the verification endpoints. Returns a one-time identity-verification link (`kyc_url`) for the calling wallet. Open it (or hand it to the wallet owner) to complete verification. The typical flow is: call `/get-kyc-status`, and only if `kyc_verified` is `false` call this to get a link, complete it, then proceed to `/send-payment`.

Register a notification webhook (free) Registers (or replaces) an HTTPS webhook URL to receive the calling wallet's account notifications as signed POSTs — banking application status changes, bank transfer and payout completions, agent wallet deposits, card orders, and every other event the user is notified about. This closes the polling gap for agents: instead of re-fetching status endpoints, point this at any URL you can receive HTTP on (your harness's inbound webhook endpoint, or a relay you poll). Deliveries are signed per the Standard Webhooks specification (https://www.standardwebhooks.com/): each POST carries `webhook-id`, `webhook-timestamp`, and `webhook-signature` (`v1,<base64 HMAC-SHA256>`) headers verifiable with any standard-webhooks library using the returned `secret`. The body is `{"type": "notification.<category>", "timestamp": "<ISO 8601>", "data": {"user_id", "title", "text", "category"}}`. The `secret` is returned exactly once, by this call. Re-registering rotates the secret, replaces the URL, and re-enables a registration that was auto-disabled after 50 consecutive failed deliveries. Registering also notifies the account owner through their other channels and fires a first signed test delivery (`type` `notification.account`) at the new URL. Deliveries time out after 10 seconds and are not retried; treat the webhook as a low-latency hint and the status endpoints as the source of truth. The URL must be public HTTPS.

Get webhook registration & delivery health (free) Returns the calling wallet's webhook registration and its delivery health. The signing secret is never returned here — it is shown once by `POST /register-webhook`; re-register to rotate it. A registration is auto-disabled after 50 consecutive failed deliveries (`disabled` becomes `true`); re-register to re-enable it.

Delete the notification webhook (free) Removes the calling wallet's webhook registration. Notifications keep flowing to the user's other channels (push, SMS, Telegram, in-app); only the webhook deliveries stop. The account owner is notified of the removal.

Withdraw from account balance Initiate a withdrawal from the user's account balance. The USDC is sent on Solana to the `solana_address` you supply; the destination is never inferred, so the address is required. This is an asynchronous operation. A successful call answers `202 Accepted`: the withdrawal is created in a `pending` state and sent within a few minutes. Poll the returned `status_url` (`GET /get-withdrawal-status?withdrawal_id=...`) until `state` reaches a terminal value rather than treating the 202 as completion.

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

Trigger a card data refresh Requests an updated balance for a card. For U.S. non-reloadable cards (default), the card is re-scraped from the issuer via a retrieval queue and processed asynchronously. Rate limited per card to one request every 5 minutes, and to at most 12 refreshes in any rolling 24-hour period. For international non-reloadable cards, a balance update request is recorded; an admin will manually update the balance within 24 hours. While a balance update is already pending for a card, additional requests for that card return 409.

Order an international prepaid card Order an international non-reloadable prepaid card (USD). The order is queued and fulfilled by an admin — after fulfillment, card details become available via `GET /get-card-data` with `card_type=Non-Reloadable International`. The x402 payment covers the on-card amount plus a 3.8% fee, or a lower rate while a limited-time fee promotion is running (it can be 0%). The 402 challenge always carries the exact total. Minimum $100, maximum $1,000 on-card amount. The $1,000 maximum is the amount loaded on the card and does not change with the fee rate. Submit a whole dollar amount. Placing the order accepts the card issuer's terms on behalf of the account holder: the [Cardholder Agreement](https://laso.finance/intl-card-cardholder-agreement.pdf), the [E-Communications Disclosure](https://laso.finance/intl-card-e-communications-disclosure.pdf), and the [Privacy Notice](https://laso.finance/intl-card-privacy-notice.pdf). If you need to cancel a queued order before it is fulfilled, use `POST /cancel-intl-order`. PAID ROUTE (100-1038 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Cancel a queued international card order Cancel a previously queued international non-reloadable card order, as long as it has not yet been fulfilled by an admin (`state=queued`). The charged amount is credited back to the account balance.

Search merchant spend data Search Laso's merchant database for confirmed spend data for a given card type. Returns whether the card was accepted, not accepted, or unknown at each merchant. Use `card_type` to search by the USA prepaid card (`Non-Reloadable U.S.`, the default) or the international prepaid card (`Non-Reloadable International`). USA searches exclude merchants with non-US country-code TLDs; international searches do not. **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. Banking and money-transfer merchants are always returned as `not_accepted` with a `restriction_note`, whatever the transaction history shows. Spending there counts as a transfer of value and is not supported on any card.

Get the fee schedule Returns the fee and limits of every paid product: the route, the `amount` range it accepts, the fee rate, and the minimum fee. Free, no auth or payment header, so you can budget before you have an account. Fees are added on top of `amount`. The total is `amount + max(amount × fee_rate, min_fee)`, rounded up to the cent. The international card's `fee_rate` is the rate in effect now, including any running fee promotion. For the exact total of one specific request, read the `amount` in that route's 402 challenge: requesting a paid route without a payment header returns the quote and charges nothing.

Get supported countries Returns where each product can be used or sent, as ISO 3166-1 alpha-2 country codes. Free, no auth or payment header. The USA prepaid card, Venmo payments, and bank payments are U.S. only. PayPal pays recipients in every country Laso serves; `countries_by_platform` separates it from Venmo. Push to card pays out to debit cards in the U.S. (`USD`), the euro area (`EUR`), and the U.K. (`GBP`); `countries_by_currency` maps each currency to its countries. The gift card list is the live catalog's: pass one of its codes as `country` to `GET /order-gift-card`. The international prepaid card has no fixed list (`countries: null`); check a merchant with `GET /search-merchants?card_type=Non-Reloadable International`.

Start a signup for a human with no Laso account Begins account creation for a human who does not have a Laso account yet. Requires no authentication, because the caller has no account. This does **not** create the account. An agent cannot: the account is created by Privy in the human's own browser, so it belongs to them and not to their agent. What this returns is a `claim_url` to hand over. Give your human the `claim_url` verbatim in your very next reply (send `message_for_human` if unsure what to say), and do not open it yourself. Then poll `GET /signup-status`, which holds the connection open until they finish and hands you your `lasoak_` API key. Rate limited per IP.

Wait for your human to finish the signup Long-polls until the human opens the claim link and finishes creating the account. Holds the connection open for about 60 seconds and returns **204 No Content** if they have not finished yet. **Retry on 204 and nothing else.** The call already blocks for you, so add no sleep between attempts. Every other status is final and retrying will not change the answer: 401 means the token is wrong, 410 means the link expired. Both carry `"terminal": true` in the body. A loop written as "retry until 200" spins at network speed against those, because they answer instantly rather than holding the connection. On completion it returns your `api_key` — **delivered exactly once**. Store it before doing anything else; a later poll returns the account without it. By that point the human is on their dashboard, their agent wallet is provisioned, and you are already recorded as their connected agent, so `announceAgentConnection` is not needed on this path.

Get a login link for the web dashboard 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 for humans who want to see what their AI agent has been doing (view cards, transactions, balances, etc.). The URL carries a short single-use login code rather than a long token, so relay it to your human verbatim; it passes through tool-output credential filters intact. Do not fetch or open the URL yourself: redeeming the code consumes the human's login.

Send feedback about the API Tell the humans running Laso what worked, what was confusing, and what you wish existed. It lands on their dashboard, so it is the best channel for API friction and feature requests. Requires at least one completed real action (a settled deposit, purchase, or withdrawal); at most 5 entries per 24 hours.

List saved recipients The saved recipient names your human manages on their dashboard, so a request like "send $20 to the coffee vendor" can be resolved to an address instead of asking them for it. Free. It operates only on the authenticated account's own book — there is no user parameter to pass. **A name is a label, not an instruction.** `agentWalletTransfer` takes an address and deliberately does not accept a name: a rename between your human asking and you sending would otherwise move money somewhere they did not intend. When you resolve a name to an address, say the address back to them before sending.

Save or rename a recipient The saved recipient names your human manages on their dashboard, so a request like "send $20 to the coffee vendor" can be resolved to an address instead of asking them for it. Free. It operates only on the authenticated account's own book — there is no user parameter to pass. **A name is a label, not an instruction.** `agentWalletTransfer` takes an address and deliberately does not accept a name: a rename between your human asking and you sending would otherwise move money somewhere they did not intend. When you resolve a name to an address, say the address back to them before sending. The address is the entry's key, so saving one that is already saved renames it rather than creating a duplicate. That makes this safe to retry.

Remove a saved recipient The saved recipient names your human manages on their dashboard, so a request like "send $20 to the coffee vendor" can be resolved to an address instead of asking them for it. Free. It operates only on the authenticated account's own book — there is no user parameter to pass. **A name is a label, not an instruction.** `agentWalletTransfer` takes an address and deliberately does not accept a name: a rename between your human asking and you sending would otherwise move money somewhere they did not intend. When you resolve a name to an address, say the address back to them before sending. Removing an entry only forgets the name; it has no effect on past transfers to that address.

Send money to a debit card (USD, EUR, GBP) Pay USDC to initiate a push-to-card transfer. Specify the face value in the target currency (USD, EUR, or GBP); Laso computes the USDC cost using the current exchange rate plus a 4.8% fee (minimum fee of $1.50/€1.50/£1.50 in the transfer currency), and that becomes the x402 price. Returns a `redemption_url` that must be opened to complete the transfer. The form requires sender name, debit card number, and cardholder name. **Supported currencies:** - `USD` — U.S. debit cards (U.S. bank accounts only) - `EUR` — Eurozone debit cards - `GBP` — U.K. debit cards Laso cannot perform the transfer directly — the redemption URL must be visited and the debit card details entered manually (by the agent or a human). **Fee:** 4.8%, with a minimum of 1.50 in the transfer currency (included in the USDC price, computed from the requested face value). PAID ROUTE (11.50-10000 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Send a payment via Venmo or PayPal Pay USDC to send money to a Venmo or PayPal recipient. The x402 USDC price is the requested amount plus a 4.9% fee (with a $1.50 minimum fee). On-chain payment credits the calling wallet's Laso account balance via the standard deposit webhook; the callable then debits the gross amount and dispatches the payout. **Asynchronous.** A dispatched payout answers `202 Accepted`, not `200`: the payment is recorded and handed to the payout provider, which settles it afterwards. Poll the returned `status_url` (`GET /get-payment-status?payment_id=...`) until `state` reaches a terminal value rather than treating the 202 as money received. A `200` means the opposite: nothing was dispatched because identity verification is required. **KYC required.** The first time a wallet sends a Venmo or PayPal payout it must complete identity verification. If the wallet is not yet verified the response returns `kyc_required: true` and a `kyc_url` — open the URL, complete the flow, and retry. If you don't want to proceed, the credited account balance can be withdrawn with `POST /withdraw`. **Recipient details.** For Venmo, `recipient_id` is the recipient's 10-digit U.S. phone number, and the first and last name are optional. No email is needed. For PayPal, `recipient_id` is the recipient's PayPal email, which also serves as `recipient_email` (so `recipient_email` is optional), and the first and last name are required. **Fee:** 4.9% with a $1.50 minimum (included in the USDC price). PAID ROUTE (6.50-1049 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Load a reloadable card balance Pay USDC to load the account holder's reloadable card balance at the card issuer. **Why this exists:** the card issuer only accepts USDC on **Base**, and a Laso managed agent wallet holds USDC on **Solana**. Pay this route from either chain and Laso bridges the payment to your own deposit address at the issuer over Circle's CCTP, which burns on the source chain and mints native USDC on Base. **Price:** exactly the amount you are loading, and exactly that amount is credited to the balance. Loading $50 costs $50 and puts $50 on the card. Laso covers Circle's bridging fee by burning slightly more than requested. **A linked card issuer account is required.** The account holder sets it up at https://laso.finance/agent/dashboard/verified/card. **Delivery starts once your payment settles.** The response confirms the payment and returns a `top_up_id`; the transfer to your card balance follows and usually lands in under a minute. A payment made on Base is already on the issuer's chain, so it is forwarded without a bridge. Watch the top-up under `top_ups` in `GET /list-card-transactions`, where `status` moves `paid` → `bridging` → `delivered` → `credited` and the transaction hash behind each leg appears as it lands, or poll `GET /get-card-deposit-address` until `balance` reflects it. **Follow with `POST /create-reloadable-card`** to create a card against the balance once it has arrived. **If the top-up's status becomes `failed`**, nothing is stranded: the USDC you paid has credited your Laso account balance. Retry, or recover it with `POST /withdraw`. PAID ROUTE (5-10000 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Withdraw from a reloadable card balance Move unspent money off the account holder's reloadable card. The balance behind a reloadable card is held by the card issuer, and this asks the issuer to pay `amount` of it out as USDC on **Base** to the `destination_address` you supply. It is the reverse of `GET /fund-card-balance`, and free: the money is the holder's own, and Laso moves nothing itself. **Base only.** The issuer pays on Base and nowhere else, so the destination must be a Base wallet you control. A Laso managed agent wallet holds USDC on **Solana** and cannot receive this. The card deposit address from `GET /get-card-deposit-address` is not a valid destination either. **Not instant.** The issuer processes payouts manually, usually within 1-3 business days, and emails the account holder when the payout is sent. The response carries the issuer's `withdrawal_id`; there is no status route to poll. The request is recorded as a `withdrawal` event under `card_events` in `GET /list-card-transactions`, and the balance from `GET /get-card-deposit-address` drops once it is paid. **Amount:** $2 to $10,000, and no more than the balance the issuer can release. Withdrawals the issuer has not paid yet still count against the balance, so a second request can only take what remains. Confirm the amount and destination with the account holder before calling this. A linked card issuer account is required; the holder sets it up at https://laso.finance/agent/dashboard/verified/card.

List saved Venmo and PayPal recipients (free) Lists the Venmo or PayPal recipients this account has paid before, so you can resolve a name your human said ("send $20 to Jane") into the `handle` that `GET /send-payment` takes as its `recipient_id`. Free — only the payout itself is a paid action. Two different ids are in play. Each entry's `recipient_id` is an opaque saved-entry id: pass it to `POST` and `DELETE /payment-recipients`. Its `handle` is the phone number or email you actually pay: pass that as `recipient_id` to `GET /send-payment`. Passing the saved-entry id to `GET /send-payment` does not send to the saved person. Use `total_sent` and `last_sent_timestamp` to disambiguate similar names, and confirm with your human rather than guessing between two entries.

Rename or archive a saved recipient (free) Renames a saved Venmo or PayPal recipient, archives it, or both. Provide at least one of `display_name` or `archived`. Archiving hides an entry from the default list while keeping its history, which is the reversible way to retire a recipient. Prefer it over `DELETE`.

Remove a saved recipient (free) Removes a saved Venmo or PayPal recipient. Payment history is kept; only the saved entry stops being offered. This is not reversible through the API, so prefer archiving (`POST /payment-recipients` with `archived: true`) when the account owner may want the recipient back, and confirm before removing someone they did not ask you to remove. `platform` and `recipient_id` may be sent in the JSON body or the query string.

Check Venmo and PayPal payout status (free) Reports the state of the Venmo and PayPal payouts this account has sent with `GET /send-payment`. Free: only the payout itself is a paid action. Three ways to call it: with `payment_id` to fetch one payout, with `recipient_id` (from `GET /payment-recipients`) to list every payout to that saved recipient, or with neither to list every payout this account has sent, newest first. `state` is `queued` (waiting on account balance), `awaiting-funding` (debited and accepted, but delayed on our side before it reaches the platform, usually until the next business day), `in-process` (dispatched to the platform), `complete`, `failed`, or `cancelled`. `queued`, `awaiting-funding` and `in-process` are the states still in flight; poll every few minutes, or register a webhook with `POST /register-webhook` to be told when a payout completes instead. A payout that has been `in-process` for more than an hour is worth raising with the account owner. `state` is absent on payouts sent before state tracking existed. Bank payouts are not listed here: follow those with `listBankingTransactions`. Push-to-card transfers are completed by the recipient in the browser and have no server-side state.

Send dollars to a bank account Pay USDC to send dollars to a bank account by ACH. The x402 USDC price is the requested amount plus a 0.25% transfer fee (with a $1.50 minimum fee). On-chain payment credits the calling wallet's Laso account balance via the standard deposit webhook; the callable then debits the gross amount and queues the transfer. **A bank destination is required first.** `destination_id` comes from the banking callables: create the banking profile with `createBankingProfile`, register who is being paid with `createBankingRecipient`, and attach their bank account with `addBankingDestination`, which returns the id. List what you already have at `GET /bank-recipients` (free). See the [bank accounts guide](/guides/agent-bank-accounts) for the full setup. **Identity verification is required** on the account that owns the banking profile, and only the human owner can complete it. `createBankingProfile` hands back a `kycUrl` when it is outstanding. **If the payout cannot be fulfilled** (no approved banking profile, a destination that is not yours, an amount out of range), nothing is stranded: the USDC you paid has already credited your account balance. Fix the problem and retry, or recover it with `POST /withdraw`. **Settlement:** ACH, normally 1-2 business days. Follow it with `listBankingTransactions` / `getBankingTransaction`. **Fee:** 0.25% with a $1.50 minimum (included in the USDC price). PAID ROUTE (11.50-50125 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Search the gift card catalog 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`. Every response includes a `facets` object listing the valid values for the `category`, `currency`, and `country` filters. The facets are computed from the full catalog, so a single unfiltered request (no query parameters) is enough to discover everything you can filter on. This is a free endpoint — no x402 payment required.

Order a gift card Pay USDC via x402 to order a gift card. First browse the catalog via `GET /search-gift-cards` to find the `laso_server_id` for the card you want, then call this endpoint with the amount and product ID. **Pricing:** `amount` is the card's face value in the product's own currency, not USD. Laso converts it to USD at the current exchange rate and adds the product's fee (up to 4.8%); that total is the x402 USDC price. A 100 SAR card costs roughly $28 USDC, not $100. Check the product's `currency` field in `GET /search-gift-cards` to see what `amount` is denominated in. The $5 minimum and $9,000 maximum apply to the **converted USD value**, not the raw amount, so a foreign-currency amount is accepted only when its USD equivalent falls inside that range. Returns redemption details (URL, code, and/or PIN) depending on the gift card brand. PAID ROUTE (5-9432 USD): the x402 USDC price is paid automatically from your managed agent wallet. Make sure the wallet exists and is funded first (get_agent_wallet).

Create the banking profile Opens the banking profile that all other banking calls hang off. Identity verification is required first; if the human has not verified, the reply carries `kycRequired: true` and a `kycUrl` to hand them. **This is the only step an agent cannot complete itself.** Retry once they finish. Free.

Check the banking profile status Reads the current state of the banking profile: whether it exists, and where its application stands. Free.

Read the banking application Reads what the application still needs. Returns `ready` (whether it can be submitted), `applicationStatus`, and the outstanding questions. The identity answers carry over from verification; what remains are non-identity questions such as employment status and source of funds, which an agent can answer itself. Free.

Answer application questions Submits answers to the non-identity application questions read from `getBankingApplication`. Call as many times as needed; each call merges. Free.

Upload a proof-of-address document Attaches a proof-of-address document to the banking application, for the cases where the partner asks for one. The application must already exist and have an individual on it, so complete the application first. **Two things reject uploads that otherwise look fine.** A `.jpg` file must be sent as `fileType: "jpeg"` — `"jpg"` is refused. And the partner caps the *decoded* size at 10MB, even though their own upload page advertises 20MB; oversized files are rejected here before the round-trip. `fileContent` accepts either a bare base64 string or a `data:` URL, so a browser `FileReader.readAsDataURL` result can be passed through unchanged. Free.

Submit the application Submits the completed application for review. If the partner rejects it as incomplete, the reply says what is still missing rather than failing opaquely. Free.

Open an on-ramp or off-ramp account Opens a banking rail. An **on-ramp** issues a virtual US bank account: dollars sent to it arrive as USDC in the managed wallet. An **off-ramp** pays out to a bank account you have registered, and is opened automatically by `/send-bank-payment`, so most agents never call this for one directly. Free.

List banking accounts Lists the account's banking rails and their details — for an on-ramp, the routing and account numbers to give whoever is paying in. The off-ramp deposit address is deliberately withheld: it is internal payout plumbing, not account detail. Free.

Create a payout recipient Creates a person or company money can be sent to. Bank details are attached separately with `addBankingDestination`. Free.

Attach bank details to a recipient Attaches a bank account or crypto address to a recipient and returns the `destination_id` that `/send-bank-payment` pays out to. Free.

List recipients and destinations Lists payout recipients and their destinations, with account numbers masked to the last four digits. This is where `destination_id` values come from. Also available as the free paywalled route `GET /bank-recipients`. Free.

Rename a destination Sets or clears a destination's nickname. This is the only editable field: bank details are immutable at the partner, so anything else wrong means deleting the recipient and creating a new one. Free.

Delete a recipient Deletes a recipient, its destinations, and any off-ramp account that paid out to it. Irreversible. Free.

Read one transaction Reads a single banking transaction — an on-ramp arriving or an off-ramp paying out — with its normalized status. Free.

List transactions Lists banking transactions for the account: money arriving over the on-ramp and paying out over the off-ramp, with normalized statuses and amounts. Free.

Exchange an API key for a session Exchanges a durable `lasoak_` API key for a short-lived `id_token` (one hour) plus a `refresh_token`, and returns an `auth_url` to hand your human so they can watch what you do. This is the first call an agent makes. The reply's `id_token` authenticates every other endpoint here. If you have no key, your human creates one at https://laso.finance/agent/dashboard — there is no other way to obtain one. Free.

Read the per-payment spend limit Returns the maximum the account owner allows for any single payment from the managed wallet: `maxPerPaymentUsdc`, plus the `min`, `max`, and `default` bounds it can be set within, all in whole USDC. The limit defaults to $1,000 and ranges from $1 to $50,000. It applies to every payment `agentX402Pay` makes, Laso routes and external `url` endpoints alike. Check an amount against this **before** attempting a payment rather than waiting to be refused. Compare the fee-inclusive total, since fees are added on top of the amount you request. Read-only to an agent: only the account owner can change the limit, from the dashboard. If a payment would exceed it, do not split it into smaller payments. Stop and tell your human. Free.

Issue an API key Issues a durable `lasoak_` API key for the account. **The raw key is returned once** — only its hash is stored, so it cannot be retrieved again. Normally the human does this from the dashboard. Free.

Call this FIRST, before any other Laso tool. Your human is watching a screen that waits for you to connect; this is what resolves it, names you in their dashboard, and starts a session in their activity stream. Introduce yourself with agent_name and message. Also returns your wallet funding state, so it doubles as your setup check.

Get your managed agent wallet: whether one exists, its Solana address, its USDC balance, and whether it needs funding. Paid tools draw from this wallet, so check it before your first paid call. Fund it by sending USDC (Solana) to wallet_address. Also returns base_wallet_address and base_balance_usdc for the Base wallet that pays external x402 endpoints settling in USDC on Base (both null until create_agent_wallet has provisioned it; base_balance_usdc is read live from chain and is also null when it could not be read). wallet_address, balance_usdc and needs_funding describe the Solana wallet only.

Create your managed agent wallets (one Solana wallet and one Base wallet per account; idempotent). Returns the Solana wallet as walletId and address, and the Base wallet as baseWalletId and baseAddress. An account created before Base support gets its Base wallet by calling this again. Fund the Solana address with USDC to pay for the paid tools; the Base wallet pays external x402 endpoints that settle in USDC on Base.

Transfer USDC out of your managed agent wallet to any Solana address, or to any Base address by setting destination_network to base (bridged over CCTP, minimum 1 USDC, maximum your spend limit; the recipient receives the amount less a 0.01% bridge fee, usually within a minute). Use this to pay someone or to move funds to another wallet you control, including funding your own Base wallet (destination_network base, destination_address your base_wallet_address). It only sends from the Solana wallet: USDC in the Base wallet cannot be transferred back out, so move over only what you plan to spend.

Pay ANY external x402-paywalled endpoint from your managed agent wallet: the target's 402 challenge is settled in USDC and the response body is returned, with the settlement transaction as txHash. A challenge offering Solana is paid from the Solana wallet. A challenge offering Base mainnet (eip155:8453) is paid from your Base wallet, with no ETH needed for gas; other EVM networks are refused. If the endpoint offers both, pin expected_network to choose which wallet pays. Paying a Base-only endpoint without a Base wallet fails: call create_agent_wallet, fund base_wallet_address with USDC on Base, and retry. txHash is the Base transaction hash for a Base payment and the Solana signature for a Solana one. The wallet balance can take up to a minute to reflect a payment, so confirm with txHash rather than an immediate balance read. Use the guardrail arguments to pin what you agreed to pay. For Laso's own paid routes, prefer their dedicated tools instead.

Search the Laso Finance agent docs (SKILL.md and the full API reference). Returns the most relevant sections. Use this for anything the tool descriptions don't answer: auth flows, funding, fees, webhooks, error handling.