REQUIRED FIRST STEP: Get authentication credentials (id_token, refresh_token, user_id) before calling any other Laso endpoint. The id_token is a Bearer token valid for ~1 hour.

MUST be called before /get-card, /send-payment, or any other Laso endpoint. GET with x402 payment ($0.001). Returns auth object with id_token, refresh_token, and expires_in (3600s), plus user_id derived from wallet address. Store the id_token for use as Authorization: Bearer header on all other endpoints.

Retrieve account balance, total deposits, and creation timestamp.

GET with Bearer id_token. Returns balance, totalDeposits, and account creation timestamp. No x402 payment required.

Order a prepaid card (US only, USD). PREREQUISITE: Call /auth first to get an id_token. WARNING: Prepaid debit cards are NOT accepted everywhere. Before ordering, ask the user what they want to buy and recommend checking /search-merchants first. Make sure the user understands this is a prepaid debit card and not all merchants accept them. The x402 payment equals the card amount ($5–$1000). Returns a card_id with status 'pending' — poll /get-card-data for card details.

PREREQUISITE: Call /auth first to obtain an id_token — this endpoint will fail without it. WARNING: Prepaid debit cards are NOT accepted everywhere. Before ordering, ask the user what they intend to purchase and recommend calling /search-merchants to check merchant acceptance. Clearly inform the user that this is a prepaid debit card and some merchants may not accept it. GET with amount query param and Authorization: Bearer {id_token} header. The x402 payment amount equals the card value. Response returns card_id with status 'pending'. Card details (number, CVV, expiry) become available after ~7-10 seconds — poll /get-card-data with the card_id until status is 'ready'.

{
  "query": {
    "amount": "number (required, card value in USD, $5–$1000)",
    "format": "string (optional: 'json' or 'html', default 'json')"
  }
}

Retrieve card status and details (number, expiry, CVV, balance, transactions). Omit card_id to list all cards.

GET with Bearer id_token. Poll every 2-3 seconds after ordering until status changes from 'pending' to 'ready'. Once ready, response includes card_details (number, expiry, CVV), transactions array, and last_updated_timestamp. No x402 payment required.

{
  "query": {
    "card_id": "string (optional, omit to list all cards)"
  }
}

Query withdrawal processing status. Returns tx_hash once processed.

GET with Bearer id_token. Optionally filter by withdrawal_id. Returns withdrawal status with tx_hash once processed. No x402 payment required.

{
  "query": {
    "withdrawal_id": "string (optional)"
  }
}

Refresh an expired id_token using a refresh_token. Returns a new id_token and user_id.

POST JSON body with refresh_token. Returns fresh auth credentials (id_token, refresh_token, expires_in) and user_id. No x402 payment required.

{
  "body": {
    "refresh_token": "string (required, the refresh token from /auth or a previous /refresh call)"
  }
}

Trigger a card data refresh (re-scrape balance and transactions from issuer). Rate limited to once per card every 5 minutes.

POST JSON body with card_id. Requires Bearer id_token. Rate limited to one request per card every 5 minutes. No x402 payment required.

{
  "body": {
    "card_id": "string (required)"
  }
}

Search whether a US merchant accepts the Laso prepaid debit card. Recommended before ordering a card to avoid surprises — prepaid debit cards are not accepted everywhere.

Recommended before /get-card so the user knows if their intended merchant accepts prepaid debit cards. GET with Bearer id_token and q query param. Returns acceptance status (accepted/not accepted/unknown) at merchants. If not accepted or unknown, let the user know so they can make an informed decision. No x402 payment required.

{
  "query": {
    "q": "string (required, merchant name to search)"
  }
}

Withdraw from account balance to connected wallet. Minimum $0.01.

POST JSON body with amount. Requires Bearer id_token. Minimum withdrawal is $0.01. Returns transaction confirmation. No x402 payment required.

{
  "body": {
    "amount": "number (required, minimum 0.01)"
  }
}