Ferramentas

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

Ferramentas de leitura

Retornam o estado da conta. Nunca movem fundos.

• get_balances — saldos de tokens nas smart accounts do usuário. 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 no cartão incluem merchant, MCC e campos de faturamento. Blocos type-específicos pra ramps, swaps, investimentos e compras no 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: status, 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 usuário, com chain ID e tipo de conta.
• get_action_status — lê o status atual de qualquer action pelo action_id. Use como fallback de polling quando seu 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 retorna um sign_url pro usuário autorizar com a passkey e um resource_uri (picnic://action/{action_id}) que você pode assinar pra receber atualizações de status em tempo real. A execução começa server-side assim que o usuário assina — não tem um passo de execute separado.

• transfer — envia um token da smart account do usuário pra 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 usuário. 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 (usuário negou na página de assinatura).