Ferramentas

O Picnic agents expõe onze ferramentas, organizadas em dois grupos. Cada chamada exige aprovação explícita de âmbito.

Ferramentas de leitura

Devolvem o estado da conta. Nunca movem fundos.

• get_balances — saldos de tokens nas smart accounts do utilizador. Cada saldo inclui assetId CAIP, endereço do contrato, símbolo, valor decimal e valor em USD/EUR/BRL.
• get_transactions — histórico paginado. assetId + formattedAmount por flow; receipts: [{chainId, txHash}] por tx. Compras com cartão incluem merchant, MCC e campos de faturação. Blocos type-específicos para ramps, swaps, investimentos e compras com cartão.
• get_profile — userId, email, ramps indexados por moeda (KYC BRL/EUR em BRLA/Avenia/Monerium com status normalizado none|pending|approved|rejected), e array cards (Gnosis Pay).
• get_card — detalhes do cartão Picnic: estado, saldos, allowances, período; assetId do token e valores decimais por moeda. Cartões virtuais herdam saldos do irmão físico.
• get_smart_accounts — lista das smart accounts (picnic + gnosisPay) controladas pela passkey do utilizador, com chain ID e tipo de conta.
• get_action_status — lê o estado atual de qualquer action pelo action_id. Usa como fallback de polling quando o teu cliente MCP não renderiza notifications/resources/updated de picnic://action/{action_id}.

Ferramentas de ação

Cada ferramenta é atómica: uma chamada MCP cobre proposta, entrega de assinatura e execução. A ferramenta devolve um sign_url para o utilizador autorizar com a passkey e um resource_uri (picnic://action/{action_id}) ao qual podes subscrever para receber atualizações de estado em tempo real. A execução arranca server-side assim que o utilizador assina — não há um passo de execute separado.

• transfer — envia um token da smart account do utilizador para um endereço 0x ou nome ENS.
• swap — faz swap entre dois asset_id CAIP (mesma chain ou cross-chain). slippage e provider opcionais. A página de assinatura mostra banner de aviso quando o slippage é ≥1%.
• card_freeze — congela o cartão Picnic (Gnosis Pay) do utilizador. Off-chain — a assinatura é verificada via EIP-1271 SIWE.
• card_unfreeze — contraparte simétrica de card_freeze.
• card_limit — altera o limite diário do cartão. Usa o padrão delay-module + scheduled-tx da Picnic (não 4337). Apenas diário.

Ciclo de vida da action

proposed → signed → submitted → broadcast → executed

Outros estados terminais: failed (revert on-chain), expired (TTL expirou antes da assinatura), rejected (utilizador negou na página de assinatura).