> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.json get /order-gift-card openapi: 3.1.0 info: title: Laso Finance x402 API version: 1.0.0 x-docs-revision: 2c5778b5ce19 x-docs-manifest: https://laso.finance/.well-known/docs-version.json contact: email: agents+support@laso.finance x-guidance: >- Laso Finance is a payment-gated (x402) API that lets an AI agent spend USDC on real-world financial products: prepaid cards (U.S. and international), gift cards, push-to-card transfers to USD/EUR/GBP debit cards, and Venmo/PayPal payouts. Payment: every paid route is an x402 v2 endpoint. Call it with no payment header to receive a 402 challenge listing the accepted networks, then replay with a signed USDC payment. Both Base (eip155:8453) and Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) are accepted on every paid route; the caller picks either chain. Identity: `GET /auth` is free and identity-only. Prove wallet ownership with a `SIGN-IN-WITH-X` (CAIP-122) header to receive a Firebase id_token, then send that token as a Bearer credential to the authenticated read routes (`get-card-data`, `get-account-balance`, `get-kyc-status`, etc.). Paid routes also return fresh auth credentials in their response, so a payment is never required just to obtain a token. Recommended flow: (1) `GET /auth` to establish identity, (2) call a paid route (e.g. `GET /get-card`) to purchase a product, paying USDC on Base or Solana, (3) poll the authenticated read routes with the returned Bearer token to fetch the resulting card/transfer details. Full machine-readable instructions live at https://laso.finance/SKILL.md. description: >- Payment-gated API for Laso Finance. All paywalled routes use the x402 protocol — the caller includes a USDC payment header on Base (eip155:8453) or Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) and the server verifies payment before processing. Free routes require no payment header. The same 402 also carries an MPP (Machine Payments Protocol) challenge in WWW-Authenticate; an MPP client pays with USDC on Base by replaying with `Authorization: Payment ...`, and routes, prices, and responses are identical. ## Getting started To set up a wallet for making x402 payments, choose a provider: - **Locus** (default): https://paywithlocus.com/SKILL.md - **Sponge**: https://wallet.paysponge.com/skill.md — automatic x402 service discovery - **Ampersend**: https://www.ampersend.ai/getting-started.md — self-custody on Base or Solana with dual-approval spending limits. Laso Finance is a default skill, so no manual endpoint registration is needed. ## How x402 works 1. Call a paywalled endpoint without a payment header → receive a `402 Payment Required` response containing payment details (price, recipient address, network). 2. Construct an x402 payment header using the details from the 402 response. 3. Replay the request with the payment header → the server verifies payment and processes the request. ## Authentication flow `GET /auth` is free: callers prove wallet ownership by sending a `SIGN-IN-WITH-X` header (CAIP-122 wallet signature). Paywalled routes (`/get-card`, `/order-gift-card`, `/get-push-to-card`, `/order-intl-card`) also return fresh auth credentials in their responses, so a payment is never required just to obtain a token. Most routes return auth credentials (`id_token`, `refresh_token`, `expires_in`). Use the `id_token` as a Bearer token to call authenticated Laso Finance endpoints like `/get-card-data`. When the `id_token` expires, use `POST /auth` with `grant_type: refresh_token` to get a new one. ## Important notes The `/get-card` USA prepaid card endpoint is U.S. only — issued in USD, usable at U.S.-based merchants only, and physical goods must ship to a U.S. address. For non-U.S. merchants or non-USD currencies, use `GET /order-intl-card` instead (international prepaid card, admin-fulfilled within 24 hours). All cards are intended for the caller's own use. ## Rate limits Every response carries the request budget so you can pace yourself without probing for a limit: | Header | Meaning | | --- | --- | | `RateLimit-Limit` | Requests permitted per window | | `RateLimit-Remaining` | Requests still available | | `RateLimit-Reset` | Seconds until the window rolls over | | `RateLimit-Policy` | The policy these numbers describe, as `limit;w=seconds` | The same values are repeated as `X-RateLimit-*` for clients that only parse that spelling. Most routes advertise the service-wide ceiling. `POST /signup` enforces its own per-IP budget on top of it and overwrites these headers with its own numbers. `POST /refresh-card-data` is limited per card rather than per caller, so its headers keep the service-wide values and the per-card budget is reported only on rejection. Every rejection is a `429` carrying `Retry-After` in seconds and a matching `retry_after_seconds` field in the body, computed from the limit that actually rejected the request. Wait that long and retry once. Do not retry in a tight loop. For step-by-step instructions, read https://laso.finance/SKILL.md servers: - url: https://laso.finance description: Production security: [] paths: /order-gift-card: get: summary: Order a gift card description: >- 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. operationId: orderGiftCard parameters: - name: amount in: query required: true description: >- Gift card face value in the product's own currency (see the product's `currency` field in `GET /search-gift-cards`), not USD. The x402 price is this value converted to USD plus the product fee. After conversion it must be worth at least \$5 and at most \$9,000 USD. schema: type: number exclusiveMinimum: 0 - name: laso_server_id in: query required: true description: >- The product identifier from the gift card catalog (GET /search-gift-cards). Always copy it from a search result; an id that is not in the catalog returns 404 `unknown_laso_server_id`. Amazon is `amazon` for every country, selected with `country`. schema: type: string - name: country in: query required: false description: ISO 3166-1 alpha-2 country code (defaults to "US") schema: type: string default: US responses: '200': description: Gift card ordered successfully content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/AuthCredentials' callable_base_url: type: string example: https://laso.finance user_id: type: string description: The user's ID (lowercase wallet address) gift_card: $ref: '#/components/schemas/GiftCardOrder' '400': description: Invalid or missing parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: laso_server_id query parameter is required '402': description: >- Payment required. No valid x402 payment header was included. The response body is an empty JSON object; the payment details (price, recipient address, network) are base64-encoded in the `PAYMENT-REQUIRED` response header. x402 client libraries handle this automatically. A **second** 402 on the paid retry means something different: the payment header verified but the transfer could not be settled on-chain. That response body is not empty and carries no `accepts` — it is the x402 settlement-failure shape `{"success": false, "errorReason": "...", "errorMessage": "..."}`, plus `x_laso_guidance` when a concrete next step applies. Distinguish the two by body: a challenge has `accepts`, a failure has `success: false`. The usual cause is an underfunded wallet, and the usual cause of that is the fee being charged **on top of** `amount` (a wallet holding exactly \$2,000 cannot send a \$2,000 payment). Nothing is charged for a failed settlement, so retrying with a smaller amount is safe. content: application/json: schema: type: object example: {} '403': description: >- Account is frozen. The response includes a `frozen_message` field explaining why. content: application/json: schema: $ref: '#/components/schemas/FrozenError' example: error: Account is frozen frozen_message: >- Your account is frozen pending a compliance review. Contact support@laso.finance. '404': description: >- `laso_server_id` matches no gift card in the catalog (`code: unknown_laso_server_id`). The check runs before a payment is quoted, so this is returned in place of the 402 challenge and nothing is charged. It is terminal: the same id will never succeed. Look up a valid id with `GET /search-gift-cards` and order with that value. content: application/json: schema: type: object properties: error: type: string code: type: string enum: - unknown_laso_server_id terminal: type: boolean laso_server_id: type: string description: The id that was sent hint: type: string search_url: type: string example: error: No gift card in the catalog has laso_server_id "amazon-usa". code: unknown_laso_server_id terminal: true laso_server_id: amazon-usa hint: >- Find a valid laso_server_id with GET /search-gift-cards (for example /search-gift-cards?q=amazon) and order with that value. No payment was taken for this request. search_url: https://laso.finance/search-gift-cards components: schemas: AuthCredentials: type: object properties: id_token: type: string description: ID token — use as Bearer token for Laso Finance APIs refresh_token: type: string description: >- Use with POST /auth (grant_type=refresh_token) to get a new id_token when it expires expires_in: type: string description: Token lifetime in seconds GiftCardOrder: type: object description: Gift card order result with redemption details. properties: card_id: type: string laso_server_id: type: string amount: type: number description: >- Gift card face value, denominated in the product's own `currency` (not USD) currency: type: string description: >- ISO 4217 code the `amount` is denominated in, e.g. `USD`, `SAR`, `EUR` example: USD country: type: string example: US redemption_url: type: - string - 'null' description: URL to redeem the gift card (if applicable) redemption_code: type: - string - 'null' description: Code to redeem the gift card (if applicable) pin_code: type: - string - 'null' description: PIN code for the gift card (if applicable) status: type: string enum: - completed timestamp: type: number Error: type: object properties: error: type: string FrozenError: type: object properties: error: type: string example: Account is frozen frozen_message: type: string description: Human-readable explanation of why the account is frozen ````