# Tuyo > Connect Tuyo to an AI. Read your money and act on it from a conversation. ## Docs - [Tuyo for AI agents](/index): Connect Tuyo to Claude, ChatGPT, Codex or Cursor. Read your money and act on it from a conversation. - [Connect Tuyo](/quickstart): Add Tuyo to Claude, ChatGPT, Claude Code, Codex or Cursor. - [Early access](/early-access): Try pods, pod managers, webhooks and the Tuyo app in ChatGPT before they reach everyone. - [How approvals work](/guides/approvals): The AI can prepare actions. You approve each one, or you approve a pod manager once. - [Pod managers](/guides/pod-managers): Let an AI move money in one pod with no approval for each action. - [Purchases](/guides/purchases): An AI buys something for the user with card details that only its own code can read. - [Vaults and pod cards](/guides/investments): Move money into and out of an investment vault, and ask for a pod card. - [Webhooks](/guides/webhooks): Send Tuyo events to an HTTPS URL. - [Errors](/guides/errors): How a tool reports an error, and what the AI should do next. - [Security](/guides/security): What the AI can and cannot do with your Tuyo account. - [MCP tools](/tools/index): Every tool the Tuyo MCP server gives an AI, with what it does and where it is available. - [get_account_status](/tools/get_account_status): Read readiness, verification, required actions and product availability. - [list_pods](/tools/list_pods): List owned pods and their accountIds, in Tuyo order (new pods last). - [create_pod](/tools/create_pod): Create a Pod: a space in Tuyo with its own balance for online purchases and investing. - [update_pod](/tools/update_pod): Rename one of the user's pods or change its color or icon, by accountId from list_pods. - [delete_pod](/tools/delete_pod): Delete one of the user's pods, by accountId from list_pods, only when the user asks. - [propose_pod_card](/tools/propose_pod_card): Ask the user to create a card that spends from a selected pod. - [get_pod_card_proposal](/tools/get_pod_card_proposal): Read the user’s answer to a request from propose_pod_card, by the id it returned. - [get_holdings](/tools/get_holdings): Read an account holdings snapshot and whole-account/matching known-value subtotals. - [get_holding](/tools/get_holding): Explain a returned holding, including previously held positions, with the same accountId and at scope. - [search_assets](/tools/search_assets): Search supported assets by text, exact coinGeckoId, category or supported network. - [get_asset](/tools/get_asset): Read an exact supported assetId from search_assets, holding.asset.id or token.assetId. - [search_vaults](/tools/search_vaults): Browse available investments by asset, risk and deposit availability. - [get_vault](/tools/get_vault): Explain an exact vaultId, including retired owned vaults. - [search_transactions](/tools/search_transactions): Find individual activity records, not period totals or reconciled statements. - [summarize_transactions](/tools/summarize_transactions): Compute period-wide spending/activity totals independently of the current group page. - [get_transaction](/tools/get_transaction): Explain an exact transactionId from search_transactions or a statement, in the same account scope. - [get_account_statement](/tools/get_account_statement): Read a reconciled main-account statement: opening/closing boundaries, activity, yield, price change and unexplained balance. - [list_transaction_categories](/tools/list_transaction_categories): List budgeting category/group codes and taxonomy version for transaction search and summaries. - [get_crypto_deposit_instructions](/tools/get_crypto_deposit_instructions): Read direct crypto deposit instructions for main or a selected account, including its exact address and supported-network allowlist. - [list_bank_deposit_accounts](/tools/list_bank_deposit_accounts): Read inbound virtual bank details for main or a selected account, with currencies available to open and any unavailability reason. - [create_bank_deposit_account](/tools/create_bank_deposit_account): Open an inbound virtual bank account immediately, without a proposal or approval step, only for a currency listed available by list_bank_deposit_accounts in the same scope. - [close_bank_deposit_account](/tools/close_bank_deposit_account): Close a pod bank deposit account immediately, without a proposal, only when the user asks. - [list_external_bank_accounts](/tools/list_external_bank_accounts): Read saved outbound bank recipients belonging to the user, another person or a business, with masked account numbers and authoritative managerExecutionEligibility. - [add_external_bank_account](/tools/add_external_bank_account): Save a bank recipient immediately after bank validation, without a proposal or approval step; this moves no money. - [propose_send](/tools/propose_send): Create a send approval request for the user to review in Tuyo; this does not execute payment. - [quote_convert](/tools/quote_convert): Estimate a buy, sell, swap or conversion without creating an approval request or moving funds. - [propose_convert](/tools/propose_convert): Create a buy, sell, swap or conversion approval request; this does not execute a trade. - [propose_vault_deposit](/tools/propose_vault_deposit): Create a request for the user to approve in Tuyo: deposit an exact amount of an investment vault's asset from the main account or a pod into that vault. - [propose_vault_withdrawal](/tools/propose_vault_withdrawal): Create a request for the user to approve in Tuyo: withdraw an exact amount of an investment vault's asset from the main account's or a pod's position back to that account's balance. - [get_proposal](/tools/get_proposal): Read the current send, conversion or vault move approval request without approving or executing it. - [list_proposals](/tools/list_proposals): List the approval requests this connection created, newest first, without approving or executing anything. - [propose_purchase](/tools/propose_purchase): Create a purchase approval request in Tuyo; issuance requires user approval and merchant payment is separate. - [prepare_purchase](/tools/prepare_purchase): Start card issuance using existing pod management access, without another per-purchase owner approval; merchant checkout is still separate. - [get_purchase](/tools/get_purchase): Read authoritative purchase status immediately by default. - [get_purchase_payment_details](/tools/get_purchase_payment_details): Reveal encrypted credentials for an active purchase. - [cancel_purchase](/tools/cancel_purchase): End the Tuyo purchase authorization and return its current authoritative state, including a charge that won a cancellation race. - [list_purchases](/tools/list_purchases): List this OAuth connection’s purchases newest first across all lifecycle states by default. - [get_manager_signer](/tools/get_manager_signer): Get on-demand secure tuyo-signer installation, key creation, identity refresh and signing guidance when the user asks to become or act as a pod manager. - [propose_pod_management](/tools/propose_pod_management): Create a request for the user to approve management of their selected pod in Tuyo. - [get_pod_management_proposal](/tools/get_pod_management_proposal): Read the exact management proposal immediately by default, with fresh managerIdentity from the original signer. - [list_pod_management_proposals](/tools/list_pod_management_proposals): Find management requests for this original signer and OAuth connection after a lost response or interruption, including approved, declined and expired history. - [list_managed_pods](/tools/list_managed_pods): List current active management for the original signer and this OAuth connection, with exact accountId, proposalId and managementExpiresAt. - [revoke_pod_management](/tools/revoke_pod_management): Give up the exact management approval the user asked to remove, using proposalId from list_managed_pods or a known management proposal. - [prepare_send](/tools/prepare_send): Prepare a send under existing pod management, without another owner approval. - [prepare_convert](/tools/prepare_convert): Prepare a buy, sell, swap or conversion under existing pod management without another owner approval. - [prepare_vault_deposit](/tools/prepare_vault_deposit): Prepare a deposit of an exact amount of an investment vault's asset from a managed pod's balance into that vault, under existing pod management, without another owner approval. - [prepare_vault_withdrawal](/tools/prepare_vault_withdrawal): Prepare a withdrawal of an exact amount of an investment vault's asset from a managed pod's position back to its balance, under existing pod management, without another owner approval. - [submit_execution](/tools/submit_execution): Submit a signature for the exact execution from prepare_send, prepare_convert, prepare_vault_deposit or prepare_vault_withdrawal. - [get_execution](/tools/get_execution): Read an exact send, conversion or vault move execution using its executionId from a prepare tool or list_executions and fresh managerIdentity from the original signer. - [list_executions](/tools/list_executions): Find this signer and OAuth connection’s send, conversion and vault move executions after a lost response or interruption; includes historical operations after revocation. - [list_webhook_events](/tools/list_webhook_events): Find the events and accepted filters for sending Tuyo activity to a public HTTPS receiver with create_webhook. - [list_webhooks](/tools/list_webhooks): List webhooks for this connection, newest first. - [create_webhook](/tools/create_webhook): Create a plain webhook to send selected Tuyo events to the user’s public HTTPS receiver. - [delete_webhook](/tools/delete_webhook): Remove one webhook by its exact id from list_webhooks or create_webhook. - [open_tuyo](/tools/open_tuyo): Open the user’s main-account Tuyo wallet, activity, holding or transaction in a host that supports MCP Apps. - [open_tuyo_panel](/tools/open_tuyo_panel): Open the main-account Tuyo wallet in a panel beside the conversation when the user asks to keep it open there. - [load_tuyo_page](/tools/load_tuyo_page): Provide one page of the main-account Tuyo wallet to the embedded app. - [search_tuyo_mentions](/tools/search_tuyo_mentions): Return main-account holding and transaction links for the host’s composer @ menu. - [feature_request](/tools/feature_request): When a real user task reveals an unmet tool, data or product need, proactively send one sanitized request to the Tuyo team. - [Get the active public API contract version](/api-reference/get-the-active-public-api-contract-version) - [Get account readiness](/api-reference/get-account-readiness) - [Get direct crypto deposit instructions](/api-reference/get-direct-crypto-deposit-instructions) - [List bank deposit accounts](/api-reference/list-bank-deposit-accounts): The user's virtual bank accounts for depositing fiat, and in available the currencies they could still open. When bank deposits are unavailable, unavailableReason says why. - [Get virtual bank-account deposit instructions (deprecated)](/api-reference/get-virtual-bank-account-deposit-instructions-deprecated): Deprecated alias of `GET /bank_deposit_accounts`, removed on 2027-01-31. Responses carry `Deprecation` and `Sunset` headers and a `meta.deprecation` notice. - [Search account transaction history](/api-reference/search-account-transaction-history): Named payloads preserve native transaction kinds. Positive card Money is outgoing; negative is incoming. Amount filters and sorting require amountField and its explicit currency or tokenId. All filters apply before keyset pagination. Default25/max100. Include operations when needed. History excludes abandoned unsubmitted checkouts and unsupported spam, but includes tiny receipts, zero corrections and reversals. This is current history, not a lossless change log. - [Get transaction detail](/api-reference/get-transaction-detail): The same named object as the list, adding bounded operation references. Follow operationsPage with operationsAfter. Transaction hashes are chain-qualified and distinct from user-operation hashes. - [Account statement for a period](/api-reference/account-statement-for-a-period): Required from, optional to (default now), maximum 366 days; date-times are used exactly, calendar dates expand to day bounds. Opening and closing holdings at the last block before each boundary, the successful transactions dated inside the period with their position movements and USD values at the time, vault yield, price change and execution effect for the period, and a per-position reconciliation that closes to the cent. Tuyo-internal moves (cash kept for interest, collateral funding and collection) are not listed. Transactions page oldest-first with first (default 250, max 500) and after; boundaries, positions and summary always cover the whole period. Token and vault fields inside transactions are {id} references into catalog. detail=summary omits the transactions list entirely. - [Summarize bounded transaction activity](/api-reference/summarize-bounded-transaction-activity): Required from/to, maximum366 days. Metrics use native field paths and partition totals by currency or concrete token ID. Entire-period totals are independent of group pagination. Card spending counts approved purchases, settled or not, unless statuses say otherwise; unknown amounts have null totals and known subtotals. - [List reviewed transaction categories](/api-reference/list-reviewed-transaction-categories) - [List cash-aware account holdings](/api-reference/list-cash-aware-account-holdings): Cash is one balance per currency, wherever Tuyo keeps it, with its interest setting and rate. Token and chain filters select whole matching groups. Summary spans all holdings, independent of page. Group and portfolio totals sum available valuations; individual unpriced values remain null. Benefits and card capacity are separate from assets. Yield is optional current-rate enrichment. Pages share a short-lived account-scoped snapshot. - [Get an owned holding including zero positions](/api-reference/get-an-owned-holding-including-zero-positions) - [Search the public asset catalog](/api-reference/search-the-public-asset-catalog) - [Get public asset detail](/api-reference/get-public-asset-detail) - [Search the public vault catalog](/api-reference/search-the-public-vault-catalog) - [Get public vault detail](/api-reference/get-public-vault-detail) - [List pods managed by the authenticated agent](/api-reference/list-pods-managed-by-the-authenticated-agent): Returns valid owner-approved management permissions for this signing key and the originating OAuth authorization, including before any on-chain installation. Pass accountId as podId when preparing an agent execution. Expired or revoked permissions and deleted pods are omitted. Empty results mean this key has no matching management permissions on this authorization. Chain installation is tracked separately; execution still validates current permission and chain state. - [Request owner approval for an agent to manage a pod](/api-reference/request-owner-approval-for-an-agent-to-manage-a-pod): Creates a pending manager request; it grants no execution access. signAddress is the EVM address derived from the agent public key. The private key stays with the agent. permissionExpiresAt is the requested access expiry; ttlSeconds is the separate time allowed for owner approval (60–86400 seconds, default 900). Retry with the same UUID Idempotency-Key and unchanged input. Only the originating authorization may read status. Owner signing happens in the Tuyo app. - [Get a manager request status](/api-reference/get-a-manager-request-status): Only the stable authorization that created the request may read it. approved means owner consent was verified; the manager relationship is established immediately while on-chain permission installation can still be pending. expired means its consent deadline or requested access expiry passed, the authorization ended, or the pod was deleted while pending. - [Prepare a pod send or convert for agent signing](/api-reference/prepare-a-pod-send-or-convert-for-agent-signing): Requires account:read on the originating OAuth authorization. The verified agent identity and podId select an approved manager, including before first installation. OAuth alone cannot prepare or execute an operation. Pass the complete signing object to offline sign_execution({signer, signing}). It signs backend-prepared hex bytes with personal_sign and fills the backend-provided submission template. The versioned envelope is generic; the CLI does not interpret payload meaning. Submit the operation signature before expiresAt. Every execution route requires Tuyo-Agent-Identity from the original manager key. Reuse the UUID Idempotency-Key after an ambiguous response; changed input returns 409. Same-chain and supported cross-chain routes share the owner financial planners. Bank sends and arbitrary calldata are not accepted. - [Get an agent execution](/api-reference/get-an-agent-execution): Requires account:read and the originating OAuth authorization; the original manager identity assertion is also required. submitted means queued or broadcast, settling means source inclusion with destination settlement pending. succeeded means financial completion. Signature material is never returned. - [Submit the agent signature for Tuyo cosigning and broadcast](/api-reference/submit-the-agent-signature-for-tuyo-cosigning-and-broadcast): Requires account:read and a valid operation signature from the approved manager key. Tuyo-Agent-Identity from the same manager key is also required. OAuth alone cannot authorize cosigning or broadcast. Repeated submission preserves the signed bytes and never cosigns twice. Returns submitted before onchain inclusion; poll status for completion. Owner approval fallback is not enabled. - [Create a pending send or convert proposal for approval in Tuyo](/api-reference/create-a-pending-send-or-convert-proposal-for-approval-in-tuyo): A `send` intent moves funds to a Tuyo username, address, or saved bank account. A `convert` intent changes one token into another: `from` is the token balance to spend and `amountIn` the exact amount of it, `to` the token to receive, possibly on another network. Quote it first with `POST /action_quotes`; the received amount is not fixed until settlement, so follow the accepted proposal to its transaction for `amountOut`. Accounts without conversions enabled get `action_unavailable`. The user has 15 minutes to approve unless `ttlSeconds` asks for another lifetime, from 60 seconds to 24 hours; a value outside that range is rejected. - [Get action proposal status](/api-reference/get-action-proposal-status): Lifecycle status of a proposal created by the same authorization. `kind` is `send` or `convert`, matching the created intent. `pending` is waiting for the user in Tuyo; `accepted` means the user signed and broadcast the exact action, and `transactionId` (when present) can be followed through `GET /transactions/{id}` for settlement; `rejected` and `expired` are final. The public intent is not repeated; keep it from the creation response. Proposals created by another client or account are indistinguishable from missing ones. - [Quote a convert before proposing it](/api-reference/quote-a-convert-before-proposing-it): Dry-runs the `convert` intent `POST /action_proposals` takes, the way approval in Tuyo would build it: the same route, fee and on-chain simulation, with nothing saved and no funds reserved. `from.amount` is everything that leaves the balance, fee included; `to.estimatedAmount` is what the route is expected to deliver; slippage can leave less. `valueLossPercent` compares the USD value of the two, so a high one flags a poor route or an amount too small for its fee. The quote is not held: approval quotes again. 422 codes: `no_route`, `insufficient_balance`, `simulation_failed` (the operation would revert) and `action_unavailable` (unknown token, or conversions not enabled). - [List external bank accounts](/api-reference/list-external-bank-accounts): The user's saved accounts at other banks, which they can withdraw to, favorites first. These are not the user's Tuyo accounts; for those, see `/bank_deposit_accounts`. Use `id` as `externalBankAccountId` in an `external_bank_account` recipient of `POST /action_proposals`. Full account numbers, IBANs, routing identifiers, and provider references are never returned. - [Add an external bank account](/api-reference/add-an-external-bank-account): Saves a bank account the user can send to: one of their own, or the account of a person or business they pay. There is no approval step; sending to it still needs a send proposal the user approves in Tuyo. The currency follows `accountType`: `us` is USD, `sepa` is EUR and `clabe` is MXN; send proposals can't pay MXN yet. The bank checks the account before it is saved, so a refused account is never listed. Adding an account the user already saved returns it with 200; a new one returns 201. 403 codes: `verification_required`, `account_frozen`. 422 codes: `validation_error`, `invalid_routing_number`, `invalid_iban`, `invalid_clabe`, and `bank_account_rejected` with the bank's reason. - [List external bank accounts (deprecated)](/api-reference/list-external-bank-accounts-deprecated): Deprecated alias of `GET /external_bank_accounts`, removed on 2027-01-31. Responses carry `Deprecation` and `Sunset` headers and a `meta.deprecation` notice. - [Propose a purchase for the user to approve in Tuyo](/api-reference/propose-a-purchase-for-the-user-to-approve-in-tuyo): Asks the user to approve a purchase the caller will make for them, such as an order on a website. Nothing is held or charged: the price is checked against what the user's card could pay right now, and the user approves it in Tuyo before any card exists. `amount` and `currency` are the merchant's final checkout total as the merchant shows it; for any currency other than USD, `usdAmount` is the caller's conversion of it to US dollars, which the user approves and pays from their US-dollar cash. `expiresAt` defaults to 24 hours and is clamped to the allowed range; set it only when the merchant charges later. `checkoutUrl` is the page where the caller checks out; it is optional, but send it whenever there is one, as Tuyo compares its domain with the merchant on the charge. Follow the intent with `GET /purchase_intents/{id}` or the `purchase_intent.updated` webhook. 422 codes: `purchase_intent_unavailable` (the account can't make purchases or has no active card), `purchase_intent_limit_exceeded` (over the card's remaining daily limit), `purchase_intent_quota` (too many open purchases, or over the daily purchase allowance) and `purchase_intent_insufficient_cash`. - [Get a purchase intent](/api-reference/get-a-purchase-intent): `pending` is waiting for the user in Tuyo; `accepted` means the user approved it and its single-use card is being prepared; `active` means the card is ready to pay; `charged` means it was paid. `rejected`, `expired`, `failed` and `canceled` are final and nothing was charged. `lastDecline` says why the latest charge on an active intent was declined. Intents proposed by another authorization or account are indistinguishable from missing ones. - [Cancel a purchase intent](/api-reference/cancel-a-purchase-intent): Cancels a purchase the caller won't pay, such as one it will propose again with a new total. Nothing is charged, and canceling a canceled intent succeeds. `purchase_intent_not_cancelable` (409) means it is being prepared, so try again in a few seconds, or it is already final. - [List webhooks for this authorization](/api-reference/list-webhooks-for-this-authorization): Returns this authorization’s webhooks with their current events, custom header names, enabled state and expiration, newest first. Deleted webhooks are not listed. Signing secrets and header values are never included. - [Get one webhook](/api-reference/get-one-webhook) - [Delete a webhook](/api-reference/delete-a-webhook): Deletes the owned webhook and cancels its pending deliveries. It no longer appears in lists and its Idempotency-Key can be used again. Deleting an unknown or already deleted webhook succeeds; an in-flight request may still arrive. - [Discover available webhook events and filter schemas](/api-reference/discover-available-webhook-events-and-filter-schemas) - [A new account transaction became available after reconciliation](/api-reference/a-new-account-transaction-became-available-after-reconciliation): An immutable snapshot captured when the first-appearance event is published. Later changes do not create another transaction.created event. The payload contains the public account UUID plus the default public feed transaction, without opt-in operations or legs. Uses Standard Webhooks HMAC-SHA256 signatures over webhook-id.webhook-timestamp.rawBody. The event ID and body remain stable across retries. Any 2xx acknowledges; 408, 429, 5xx and network failures retry up to six attempts with exponential backoff starting at 30 seconds. Other statuses, including 410 and 413, are not retried. Every attempt checks authorization, current transaction visibility and SSRF-safe DNS resolution. No history replay: cursor is null. Callback verification sends a signed {type:"verification",challenge} control body and requires the same challenge in a successful JSON response. - [An existing account transaction changed its top level status](/api-reference/an-existing-account-transaction-changed-its-top-level-status): An immutable snapshot captured when the top-level public status changes. First appearance and metadata-only changes do not emit an update. Omit filters for all transactions, supply kinds for selected kinds, or transactionId for one public transaction ID. When both filters are supplied, both must match. Status filters are not supported. The payload contains the public account UUID plus the default public feed transaction, without opt-in operations or legs. Uses Standard Webhooks HMAC-SHA256 signatures over webhook-id.webhook-timestamp.rawBody. The event ID and body remain stable across retries. Any 2xx acknowledges; 408, 429, 5xx and network failures retry up to six attempts with exponential backoff starting at 30 seconds. Other statuses, including 410 and 413, are not retried. Every attempt checks authorization, current transaction visibility and SSRF-safe DNS resolution. No history replay: cursor is null. Callback verification sends a signed {type:"verification",challenge} control body and requires the same challenge in a successful JSON response. - [A purchase intent you proposed changed status](/api-reference/a-purchase-intent-you-proposed-changed-status): Sent when the user approves or rejects it, its card becomes ready to pay, it is charged, or it expires, fails or is canceled. Only the authorization that proposed it receives it. Omit filters for every purchase intent, or supply purchaseIntentId for one. The payload is the purchase intent as `GET /purchase_intents/{id}` returns it at that change, plus the public account UUID. Uses Standard Webhooks HMAC-SHA256 signatures over webhook-id.webhook-timestamp.rawBody. The event ID and body remain stable across retries. Any 2xx acknowledges; 408, 429, 5xx and network failures retry up to six attempts with exponential backoff starting at 30 seconds. Other statuses, including 410 and 413, are not retried. Every attempt checks authorization and SSRF-safe DNS resolution. No history replay: cursor is null. Callback verification sends a signed {type:"verification",challenge} control body and requires the same challenge in a successful JSON response.