Floe Working Capital

Concede a agentes de IA (Claude, Cursor, personalizados) acesso total a capital de giro para pagar recibos x402.

Documentação

@floelabs/mcp-server

Floe via MCP — saiba o que cada chamada de IA realmente custa. A Floe precifica cada chamada no momento em que ela termina, em todos os fornecedores — telefonia, STT, LLM, TTS, ferramentas — em um único livro-razão, vincula o gasto ao cliente e à campanha, e mostra sua margem por contrato, para que você possa cobrar seus próprios clientes com base nesses valores reais. Este servidor coloca essa camada no seu cliente MCP: dê ao Claude Desktop, Claude Code, Cursor, CrewAI ou qualquer cliente MCP uma única chave para cada ferramenta de voz e modelo que um agente de voz usa — STT, TTS, LLM, telefonia — além de mais de 2.000 serviços de API de fornecedores, com orçamentos sobre os quais o agente pode raciocinar. Sem carteira. Sem necessidade de cripto.

Website · Docs · Dashboard · 𝕏 @FloeLabs

88 ferramentas cobrindo todo o ciclo de vida do agente — crie agentes, emita/rotacione chaves, defina orçamentos, estime custos e execute pagamentos x402 — com autenticação ciente do transporte (HTTP remoto usa um token Bearer; stdio local lê FLOE_API_KEY do ambiente) e um nível sem chave (get_markets, check_x402_url, search_floe_docs funcionam sem nenhuma chave).

Comece grátis. Um Crédito de Boas-Vindas de $3 (300 créditos de API) no cadastro — sem cartão, sem carteira. Obtenha uma chave de agente →

Comece a construir com a Floe

Uma chave para toda a conta de fornecedores do seu agente — LLM, voz, telefonia, busca, dados — medida por chamada e limitada por orçamento. Deixe seu agente de codificação configurar, ou configure você mesmo:

Caminho	Uma linha
Agente — Claude Code / Cursor faz a configuração	cole: `Read https://dev-dashboard.floelabs.xyz/agents.md and set up Floe for this project.`
Skill — instale a skill de agente da Floe	`npx skills add floe-labs/agent-skills`
MCP — servidor MCP hospedado (88 ferramentas)	`npx -y add-mcp https://mcp.floelabs.xyz/mcp`
CLI — a plataforma completa do seu terminal: agentes, chaves, orçamentos, cobrança	`npx @floelabs/cli init`
NPM — o SDK + CLI `floe-agent`	`npm i -g floe-agent`

Novas contas recebem um Crédito de Boas-Vindas de $3 (300 créditos de API) — sem cartão. Configure com suas ferramentas de IA → · Obtenha uma chave →

O que torna isso diferente

A maioria das ferramentas de pagamento permite que um agente gaste. A Floe permite que um agente raciocine sobre o gasto antes de se comprometer — e o impede antes de estourar o limite.

Ferramentas de consciência do agente — get_credit_remaining, estimate_x402_cost, get_loan_state: seu agente pergunta "tenho orçamento? essa chamada vale a pena?" antes de pagar, não depois.
Orçamentos cientes do contexto — defina um limite de gasto por sessão; o agente reduz conforme se aproxima do limite e replaneja para terminar dentro do orçamento.
A skill de agente da Floe (Floe-Labs/agent-skills) — o manual que transforma essas ferramentas em comportamento de gasto deliberado. Ir para ela ↓
Aplicação no servidor — o sinal suave é a skill; o teto rígido é o limite de gasto on-chain + a lista de permissões do comerciante. O agente não pode gastar demais independentemente do que decidir.

Início rápido (remoto, recomendado)

Instalações em uma linha:

# Universal (any MCP-aware client)
npx -y add-mcp https://mcp.floelabs.xyz/mcp

# Claude Code
claude mcp add --transport http floe https://mcp.floelabs.xyz/mcp --header "Authorization: Bearer YOUR_FLOE_KEY"

# Codex (reads the key from $FLOE_API_KEY at connect time)
codex mcp add floe --url https://mcp.floelabs.xyz/mcp --bearer-token-env-var FLOE_API_KEY

Ou por configuração JSON:

{ "mcpServers": { "floe": {
  "url": "https://mcp.floelabs.xyz/mcp",
  "headers": { "Authorization": "Bearer floe_YOUR_AGENT_KEY" }
} } }

Obtenha sua chave de agente: dashboard → Criar agente → copie a chave floe_<hex> (exibida uma vez). Ou pela CLI: npx @floelabs/cli init — cole sua chave de desenvolvedor do dashboard e ela cria (ou seleciona) o agente e emite a chave para você. Ainda sem chave? O servidor funciona mesmo assim — veja Nível sem chave.

Parâmetros de escopo — restrinja o que uma sessão pode fazer direto da URL:

https://mcp.floelabs.xyz/mcp?read_only=true          # only non-mutating tools
https://mcp.floelabs.xyz/mcp?features=spend,pricing  # only the named capability groups

Grupos de capacidade: lending, spend, pricing, lifecycle, observability, payments, webhooks, actuals, contracts, outcomes, docs. Ambos os parâmetros se combinam. O loop de decisão da skill de agente da Floe precisa de spend,pricing.

→ Stdio local, instalação global e taxonomia de chaves abaixo

Ferramentas em resumo

Grupo	Ferramentas	Para
Execução de pagamento ⭐	`x402_pay` (idempotente), `x402_forecast`, `estimate_x402_cost`, `check_x402_url`	pagar qualquer fornecedor x402 — com uma pré-verificação de custo antes
Ciclo de vida do agente	`create_agent`, `list_agents`, `get_agent`, `pause_agent`, `resume_agent`, `close_agent`, `create_agent_key`, `rotate_agent_key`, `revoke_agent_key`, `set_agent_key_budget`, `open_credit_line`, `get_credit_line_bounds`	inicializar e gerenciar a frota com uma chave de desenvolvedor
Consciência do agente ⭐	`get_credit_remaining`, `get_loan_state`, `get_spend_limit`, `set_spend_limit`, `clear_spend_limit`	todo agente — raciocine sobre o custo antes de pagar
Governança de gastos	`register_credit_threshold`, `list_credit_thresholds`, `delete_credit_threshold` (webhooks)	governe + alerte sobre a utilização
Lista de permissões do comerciante	`set_allowlist_mode`, `get_allowlist_mode`, `add_allowlist_entry`, `remove_allowlist_entry`, `list_allowlist`	negação por padrão sobre quais destinos o agente pode pagar
Financiamento e observabilidade	`get_funding_instructions`, `get_balances`, `get_activity`, `get_usage_summary`, `get_coverage_score`	financie agentes + acompanhe o gasto da frota + meça a cobertura de aplicação
Webhooks	`create_webhook`, `list_webhooks`, `list_webhook_events`, `get_webhook`, `update_webhook`, `delete_webhook`, `test_webhook`, `rotate_webhook_secret`, `list_webhook_deliveries`, `get_webhook_delivery`, `retry_webhook_delivery`	notificações push para eventos de conta + o log de entrega
Valores reais de fornecedores	`list_vendor_cost_legs`, `list_vendor_cost_calls`, `get_vendor_cost_rollup`, `list_reconciliation_findings`, `list_vendor_connections`, `verify_vendor_connection`	o que seus PRÓPRIOS fornecedores cobraram, reconciliado com os registros de cobrança deles
Interações (por tarefa)	`list_interactions`, `get_interaction`, `get_interaction_cost_rollup`	o mesmo dinheiro no nível da TAREFA — uma chamada/SMS/trabalho com cada etapa de fornecedor unida, além do custo por minuto
Contratos (assinados)	`list_contracts`, `get_contract`	o que você ASSINOU por cliente — termos, progresso do compromisso e o desvio do que a tabela de preços está realmente cobrando
Resultados (o que uma tarefa produziu)	`emit_outcome`, `list_outcomes`, `get_outcome`	relate um resultado cobrável contra um id de tarefa — a Floe o vincula à chamada, então custo e resultado ficam na mesma linha — depois encontre reivindicações pela chamada
Docs	`search_floe_docs` (sem chave)	aprenda a API da Floe sem sair do MCP
Carteira	`get_wallet_balance`, `get_accrued_interest`	saldos + estado
Utilitário	`simulate_transaction`, `broadcast_transaction`, `get_transaction_status`	ciclo de vida de transações
Protocolo de empréstimo (avançado)	20+ ferramentas de intenção / garantia / liquidação	empréstimos nativos em cripto contra depósitos

A referência completa por ferramenta está em Ferramentas (88) abaixo.

Clientes testados

Cliente	Status
Claude Desktop	`GA`
Claude Code	`GA`
Cursor	`GA`
Continue / Cline	Melhor esforço
CrewAI (via `langchain-mcp-adapters`)	`Beta`
OpenAI Agents SDK	`Preview` (fallback MCP enquanto o adaptador nativo não sai)
ElizaOS	`Preview`

Opções de instalação

A opção 1 (remota) está em Início rápido acima. Para execuções locais:

Local via npx

Execute o servidor localmente. Ele faz proxy de todas as solicitações para a API da Floe.

FLOE_API_KEY=floe_YOUR_AGENT_KEY npx -y @floelabs/mcp-server --stdio

Configuração do Claude Desktop:

{
  "mcpServers": {
    "floe": {
      "command": "npx",
      "args": ["-y", "@floelabs/mcp-server", "--stdio"],
      "env": {
        "FLOE_API_KEY": "floe_YOUR_AGENT_KEY"
      }
    }
  }
}

Configuração do Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "floe": {
      "command": "npx",
      "args": ["-y", "@floelabs/mcp-server", "--stdio"],
      "env": {
        "FLOE_API_KEY": "floe_YOUR_AGENT_KEY"
      }
    }
  }
}

Instalar globalmente

npm install -g @floelabs/mcp-server
FLOE_API_KEY=floe_YOUR_AGENT_KEY floe-mcp --stdio

Seleção de transporte

--stdio e --http são substituições explícitas. Sem nenhuma das flags, o servidor escolhe com base no que é o stdin: um pipe (um cliente MCP o iniciando) → stdio; um terminal ou o gerenciador de serviços /dev/null → HTTP em 127.0.0.1:3100. Portanto, uma configuração command: npx simples agora funciona — mas mantenha --stdio nas configurações mesmo assim para que o comportamento nunca dependa de como o cliente conecta o stdio. Em falha de inicialização, o processo registra [floe-mcp] Fatal: no stderr e sai com código 1; no modo stdio, todo o registro vai para o stderr, nunca para o stdout (que carrega o protocolo MCP).

Modelo de autenticação

A fonte de autenticação depende do transporte:

Transporte	Fonte de identidade
HTTP remoto (`https://mcp.floelabs.xyz/mcp`)	cabeçalho `Authorization: Bearer <key>` (por solicitação)
Stdio local (`floe-mcp --stdio` / `npx -y @floelabs/mcp-server --stdio`)	variável de ambiente `FLOE_API_KEY`
HTTP local (auto-hospedado)	cabeçalho `Authorization: Bearer <key>` (por solicitação). A chave de variável de ambiente nunca é usada como fallback para solicitações HTTP sem cabeçalho — solicitações sem Bearer são executadas sem chave.

Nível sem chave

O servidor inicia (e o endpoint hospedado responde) sem nenhuma chave. Sessões sem chave obtêm exatamente três ferramentas com resultados ao vivo: get_markets, check_x402_url e search_floe_docs — o suficiente para avaliar um fornecedor, precificar uma chamada e aprender a API antes do cadastro. Todas as outras ferramentas retornam um erro estruturado:

{ "error": "AUTH_REQUIRED", "status": 401,
  "message": "…Requires an agent key (floe_...).",
  "next": "Get a developer key at https://dev-dashboard.floelabs.xyz, then mint agent keys with create_agent_key. …" }

Erros de ferramenta sempre carregam o status HTTP do backend (para que agentes possam distinguir 401/403/404/429), e 401/403 incluem uma dica de correção que distingue chave ausente de tipo de chave errado.

Qual chave usar

Dois formatos de chave desbloqueiam superfícies diferentes — cada descrição de ferramenta informa qual é necessária:

Formato de chave	Escopo	Desbloqueia
`floe_<64-hex>` (chave de agente)	Um agente específico	Tempo de execução: consciência do agente, governança de gastos, lista de permissões, reputação, `estimate_x402_cost`, `x402_forecast` e `x402_pay`. Uma sessão MCP = um agente. Ferramentas de ciclo de vida retornam 401 (tipo de chave errado).
`floe_live_<base62>` (chave de desenvolvedor)	Conta inteira de desenvolvedor	Ciclo de vida: `create_agent`, chaves de agente (`create_agent_key`, `rotate_agent_key`, …), orçamentos, linhas de crédito, instruções de financiamento, saldos, atividade, uso, webhooks. Ferramentas de tempo de execução do agente retornam 401 (tipo de chave errado).

Inicialização típica: conecte com a chave de desenvolvedor → create_agent → create_agent_key → reconecte (ou abra uma segunda sessão MCP) com a chave de agente emitida para gastar.

Obtenha uma chave de agente:

Vá para dev-dashboard.floelabs.xyz
Conecte sua carteira e Crie um agente (nome + limite de empréstimo + taxa máxima)
Copie a chave floe_<64-hex> mostrada no final do assistente — ela é revelada uma única vez

Você também pode emitir uma pela CLI:

# Platform CLI — interactive: paste your developer key, create or select an
# agent, and the minted agent key lands in your OS keychain
# (manage agent keys later with `floe keys list|create|rotate|revoke`,
#  developer keys with `floe devkeys`)
npx @floelabs/cli init

# SDK-level alternatives:
# TypeScript SDK
npx floe-agent register --name my-agent --borrow-limit 10000

# Python SDK
floe-agent register --name my-agent --borrow-limit 10000

A CLI da plataforma e este servidor MCP cobrem a mesma superfície de API. @floelabs/cli é a plataforma completa a partir de um terminal — agentes, chaves, orçamentos, políticas, cobrança, fundos, telefone, chamadas medidas — com --json em cada comando e códigos de saída estáveis para scripts e CI. O MCP continua sendo a integração contextual mais rica: ferramentas que seu agente descobre, raciocina e chama no meio da sessão sem recorrer a shell.

Obtenha uma chave de desenvolvedor (desbloqueia as ferramentas de ciclo de vida — create_agent, emissão de chaves, orçamentos, financiamento, webhooks — e visibilidade multi-tenant em todos os seus agentes):

Vá para dev-dashboard.floelabs.xyz/keys
Clique em Criar Chave, dê um rótulo, escolha permissões de read ou read_write
Copie a chave floe_live_<base62> mostrada uma única vez

Chaves de desenvolvedor abrangem toda a conta de desenvolvedor e têm um limite de taxa separado (100 req/min). Ferramentas de tempo de execução do agente (get_credit_remaining, get_spend_limit, x402_pay, etc.) retornam 401 com uma chave de desenvolvedor porque o chamador é o desenvolvedor, não um único agente — a dica next do erro diz isso e aponta para create_agent_key. Veja a documentação de Chaves de API para a taxonomia completa.

Financie com moeda fiduciária: Você pode financiar sua carteira com USDC via Coinbase — cartão de crédito, transferência bancária, Apple Pay, Google Pay — diretamente do dashboard. Sem necessidade de on-ramp de cripto.

Múltiplos agentes

Um desenvolvedor Floe pode possuir muitos agentes. Para executar várias sessões MCP lado a lado (por exemplo, um agente de pesquisa e um agente de negociação), emita uma chave por agente e configure cada entrada de cliente MCP com sua própria chave:

{
  "mcpServers": {
    "floe-research": {
      "url": "https://mcp.floelabs.xyz/mcp",
      "headers": { "Authorization": "Bearer floe_KEY_FOR_RESEARCH_AGENT" }
    },
    "floe-trading": {
      "url": "https://mcp.floelabs.xyz/mcp",
      "headers": { "Authorization": "Bearer floe_KEY_FOR_TRADING_AGENT" }
    }
  }
}

Cada sessão é limitada a um agente — linhas de crédito, limites de gasto e webhooks permanecem isolados.

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`FLOE_API_KEY`	Não (nível sem chave sem ela)	—	Sua chave de API Floe: `floe_<64-hex>` chave de agente para ferramentas de runtime/gastos, `floe_live_<base62>` chave de desenvolvedor para ferramentas de ciclo de vida. Fonte de identidade no modo stdio; ignorada para requisições HTTP, que autenticam por requisição via `Authorization: Bearer`
`FLOE_API_BASE_URL`	Não	`https://credit-api.floelabs.xyz`	Endpoint da API
`MCP_PORT`	Não	`3100`	Porta do servidor HTTP (modo não-stdio)
`MCP_HOST`	Não	`127.0.0.1`	Endereço de bind HTTP; defina `0.0.0.0` para expor além do loopback
`MCP_TRUSTED_ORIGINS`	Não	—	Origens extras separadas por vírgula permitidas pelo CORS no modo HTTP

Ferramentas (88)

Abaixo, as ferramentas estão listadas por tipo de requisição. O resumo está em Ferramentas de relance acima. Cada descrição também nomeia a chave necessária: chave de agente (floe_...), chave de desenvolvedor (floe_live_...), qualquer chave, ou nenhuma. A tag de grupo de recurso em cada título é o que ?features= filtra.

Execução de pagamento (`payments`, `pricing`) ⭐

A razão pela qual o resto existe: estimar → prever → pagar. x402_pay precisa de uma chave de agente; check_x402_url não requer chave.

Ferramenta	Descrição
`x402_pay`	Executa uma chamada x402 paga através do proxy Floe — paga o fornecedor em USDC a partir do saldo/crédito do agente, retorna a resposta do fornecedor + cabeçalhos de medição `X-Floe-*`. `idempotency_key` faz com que tentativas sejam repetidas em vez de pagar duas vezes
`x402_forecast`	Previsão de custo em lote + pré-verificação de política para até 50 chamadas planejadas (com contagens de repetição) — uma única ida e volta para validar um plano inteiro
`estimate_x402_cost`	Pré-verificação de uma URL x402 — retorna custo + reflexão contra seu crédito, sem pagamento
`check_x402_url`	Sonda sem chave: esta URL é protegida por x402 e quanto custa?

Ciclo de vida do agente (`lifecycle`) — chave de desenvolvedor

Inicialize e gerencie a frota sem tocar no painel.

Ferramenta	Descrição
`create_agent`	Provisiona um agente gerenciado: carteira Privy + delegação on-chain patrocinada + o crédito de boas-vindas de $3 na primeira conta do agente (uma vez por conta, imediatamente utilizável)
`list_agents`	Lista todos os agentes na conta com status e limites
`get_agent`	Detalhe de um agente: status, endereço de depósito, crédito usado, atividade de 24h
`pause_agent`	Suspende um agente (interruptor de segurança) — suas chaves falham na autenticação até serem retomadas
`resume_agent`	Reativa um agente pausado
`close_agent`	Encerra um agente de forma irreversível: paga empréstimos, varre fundos, desativa chaves
`create_agent_key`	Emite uma chave de agente `floe_...` (texto simples uma vez), opcionalmente com um orçamento de gastos contínuo
`rotate_agent_key`	Revoga e re-emite atomicamente uma chave (novo texto simples uma vez)
`revoke_agent_key`	Exclui uma chave — chamadas que a usam falham imediatamente
`set_agent_key_budget`	Define/atualiza um orçamento contínuo de falha fechada em uma chave
`open_credit_line`	Atualiza um agente de pagamento conforme o uso para uma linha de crédito gerenciada (colateral da sua carteira)
`get_credit_line_bounds`	Pré-visualiza faixas válidas de depósito/LTV antes de `open_credit_line`

Financiamento e observabilidade (`observability`) — chave de desenvolvedor

Ferramenta	Descrição
`get_funding_instructions`	"Como financiar este agente" legível por máquina: endereço de depósito USDC, cadeia 8453, mínimos/avisos
`get_balances`	Agrega USDC entre carteira de desenvolvedor, carteiras de agente e créditos de API
`get_activity`	Feed de atividade unificado (chamadas de proxy, onramps, transferências, empréstimos) com filtros + paginação por cursor
`get_usage_summary`	Resumo de análise de gastos/uso: KPIs, série diária, principais endpoints
`get_coverage_score`	Pontuação de Cobertura: parcela de gastos conhecidos que o Floe aplica pré-chamada vs reconciliado (fora do caminho) vs escuro. Passe `agent_id` para um agente, omita para a frota

Webhooks (`webhooks`) — chave de desenvolvedor

Ferramenta	Descrição
`create_webhook`	Registra um endpoint para eventos da conta (segredo de assinatura mostrado uma vez). Escopos: `global`, `wallet`, `agent` (endereço da carteira do agente), `loan`; eventos aceitam nomes exatos, ``, ou curingas de prefixo como `call.`
`list_webhooks`	Lista webhooks registrados (segredos nunca retornados)
`list_webhook_events`	O catálogo de eventos ao vivo — 30 eventos em empréstimo / agente / crédito / chamada / telefone / marketplace
`get_webhook`	Um webhook + suas estatísticas de entrega (pendente/sucesso/falha/repetindo/total)
`update_webhook`	Altera URL, eventos, descrição, ou pausa/retoma via `active` (escopo é imutável)
`delete_webhook`	Exclui um endpoint permanentemente
`test_webhook`	Envia uma entrega de teste assinada para verificar a conectividade de ponta a ponta
`rotate_webhook_secret`	Rotaciona o segredo de assinatura (novo segredo mostrado uma vez)
`list_webhook_deliveries`	Log de entrega em toda a conta com filtros (endpoint, evento, carteira do agente, status, intervalo de tempo, id de entrega/correlação) + paginação por cursor; retenção de 30 dias
`get_webhook_delivery`	Uma entrega completa: payload enviado, corpo de resposta sanitizado, próximo tempo de repetição
`retry_webhook_delivery`	Reentrega manualmente uma entrega com falha (dedupe em `X-Floe-Delivery-Id`)

Valores reais do fornecedor (`actuals`) — chave de desenvolvedor

O que seus próprios fornecedores cobraram de você (FLO-746), reconciliado com os registros de cobrança desses fornecedores — não o que o Floe cobrou de você. Cada custo carrega um status, e um status é uma afirmação:

Status	Significa	Nunca diga
`exact`	reconciliado com o registro de cobrança por requisição do próprio fornecedor	—
`period-rate`	precificado na taxa realizada do próprio fornecedor para aquele período	"exato", ou qualquer coisa que implique precisão por requisição
`invoiced`	fundamentado na fatura do fornecedor	—
`pending`	o fornecedor ainda não publicou este custo	qualquer valor em dólares
`manual`	nenhuma API do fornecedor publica isso — envie a fatura	qualquer valor em dólares

costRaw é null para pending e manual — reporte unidades, nunca um zero. exact e period-rate são retornados como subtotais separados e nunca devem ser somados em um único número.

Quando um custo chega: algumas pernas podem ser precificadas no momento em que uma chamada termina, outras apenas no lote do dia seguinte do fornecedor — então uma perna recente lê pending, que é o estado estável, não um defeito.

A cobertura lê baixa em contas com uso intenso de voz no lançamento — uma propriedade do que os fornecedores publicam, não da sua configuração. Feche a lacuna via a via da fatura.

Ferramenta	Descrição
`list_vendor_cost_legs`	Custo de fornecedor capturado por perna com o próprio id de requisição do fornecedor, unidades tipadas, status e proveniência. Paginação por keyset. Filtros: `since`/`until`, `vendor`, `customer_id`, `agent_id`, `campaign_id`, `task_id`, `status`
`list_vendor_cost_calls`	Resumo por chamada no lado do servidor — uma contagem `composition` por chamada mais subtotais separados exatos / taxa de período. Um único `totalRaw` apenas quando cada perna é precificada e em USD; caso contrário, `"partial — lower bound"`
`get_vendor_cost_rollup`	Totais por `customer`, `campaign`, `agent`, `vendor`, ou `time` (dia UTC)
`list_reconciliation_findings`	Tudo o que o mecanismo não pôde reconciliar — pernas/valores reais sem correspondência, incompatibilidades de unidades, conectores obsoletos, variação de fatura. As razões nomeadas pelas quais um total é um limite inferior
`list_vendor_connections`	Suas credenciais de cobrança do fornecedor (mascaradas — material de chave nunca é retornado) + o catálogo de conectores. `bestStatus` é o teto: um conector `period-rate` nunca produzirá `exact`
`verify_vendor_connection`	Re-verifica uma credencial armazenada contra o fornecedor agora. Distingue "revogada, re-chaveie" (`unauthorized`) de "o fornecedor está fora" (`degraded`). Aviso — uma aprovação não é uma garantia de escopo

Por tarefa, não por fornecedor. As três ferramentas abaixo são o mesmo dinheiro no grão de interação: uma tarefa de IA — uma chamada de voz, um SMS, ou um trabalho não-chamada — com cada perna de fornecedor dessa tarefa unida em um único custo. Essa união é a unidade de COGS, e é a pergunta que nenhum painel de fornecedor pode responder: Twilio vê minutos, OpenAI vê tokens, apenas a interação vê uma chamada.

Ferramenta	Descrição
`list_interactions`	Uma linha por tarefa com duração, os fornecedores envolvidos, uma divisão por tipo de perna (`byKind`) e `topKind` — a perna que dominou o custo. `order_by="cost"` é a lista de outliers. A primeira página também carrega `distribution` (p50/p95/máx por tarefa) e `resolution` (pernas vinculadas a uma tarefa, com uma razão nomeada para cada uma que não está)
`get_interaction`	Uma tarefa aberta: cada perna em ordem de tempo com unidades, fonte de captura, status e custo, além dos identificadores pelos quais foram unidas (`links` — CallSid, ids de requisição do fornecedor, o id de tarefa Floe). Um id mesclado resolve para a tarefa canônica e reporta `requestedId` em vez de 404
`get_interaction_cost_rollup`	Custo e custo por minuto por `customer`, `campaign`, `agent`, `channel` ou `outcome` — a interação é o único grão que sabe quanto tempo o trabalho levou

Dois tipos de dinheiro, nunca somados pelo agente. Os valores reais reconciliados do fornecedor (exactRaw, periodRateRaw, totalRaw) são o que seus próprios fornecedores cobraram de você. floeChargeRaw é o que Floe cobrou pelas pernas que o Floe carregou (sem chave, Floe Phone, x402) — essas pernas não carregam fatura de fornecedor sua. paidRaw é a soma do próprio servidor dos dois, e é nulo enquanto a metade do fornecedor ainda estiver parcial. floeChargeRaw é null, não zero, quando o Floe não carregou nada.

costPerMinuteRaw é declarado apenas quando o custo é um total real, cada tarefa na linha foi fechada e a duração é positiva — caso contrário, é nulo e costPerMinuteBlockedBy nomeia o porquê (partial_cost / open_interactions / no_duration). Um $/min com duração desconhecida é incognoscível, não um limite inferior.

Gating: list_interactions e get_interaction são leituras de ledger por tarefa gratuitas (ledger_read). As quatro leituras de valores reais do fornecedor e get_interaction_cost_rollup precisam de attribution_reports, que é gratuito desde P2.6; as duas ferramentas de conexão precisam do recurso Agency vendor_connections (e admin/proprietário para verify_vendor_connection).

Não exposto via MCP, de propósito. O upload de fatura é um PUT binário para uma URL de armazenamento assinada — nenhum agente tem um arquivo para enviar. Fundamentar uma fatura escreve carimbos invoiced contra a fatura de um fornecedor e não é desfeito ao re-executar, então essa ação financeira irreversível mantém um humano no loop. Resolver um achado é um veredito humano — a API recusa o próprio auto_cleared da máquina exatamente por essa razão. Criar uma conexão escreve uma credencial selada, e credenciais nunca viajam por uma chamada de ferramenta. Todos os quatro vivem no painel e em floe actuals.

Contratos (`contracts`) — chave de desenvolvedor

O que você assinou, não o que você gastou. actuals é o que seus fornecedores cobraram de você; isso é o que seu cliente concordou em pagar. São grupos de capacidade separados de propósito, para que um operador possa entregar um sem o outro — termos comerciais e custos de fornecedores são sensíveis em direções diferentes.

Ferramenta	Descrição
`list_contracts`	O livro de contratos, do termo mais recente para o mais antigo: datas dos termos, volume comprometido, a versão da tabela de preços fixada na assinatura e `consumed` — progresso do compromisso contado na unidade própria do contrato. `needsRenewalCount` é o número de termos que expiraram sem sucessor
`get_contract`	Um contrato por id. Um contrato em outra conta responde 404, não 403, para que o endpoint nunca confirme que um id existe em outro lugar. Não carrega `consumed` — use `list_contracts` para o progresso do compromisso

status e state respondem perguntas diferentes. status é o ato humano armazenado — active ou cancelled, e nunca expired. state é o que o contrato é agora (scheduled / active / expired / cancelled), derivado do termo e do relógio a cada leitura. Um termo que expirou no mês passado ainda lê status=active, então julgue a vigência por state. A expiração é derivada em vez de armazenada justamente para que nenhum job em segundo plano possa parar silenciosamente e deixar um termo concluído parecendo ativo.

Um contrato expira; ele nunca renova automaticamente. Quando um termo termina, o uso continua sendo tarifado pela tabela de preços — a cobrança nunca para silenciosamente — mas o contrato aparece em needsRenewalCount em vez de se renovar. O sistema não compromete uma agência a termos que ninguém aceitou.

consumed pode ser um piso, e diz isso. É contado na unidade do contrato, independentemente do que a tabela de preços mede — um cliente pode se comprometer com 10.000 task enquanto a tabela cobra por audio_minute, e isso ainda é mensurável porque o livro-razão carrega cada uma dessas quantidades. Quando isLowerBound é verdadeiro, as requisições medidas não carregavam id de tarefa, então a contagem é um PISO: relate "pelo menos X de N", nunca um "X de N" simples, ou você dirá a um cliente que ele está atrás de um compromisso que talvez já tenha cumprido. consumed: null significa que não foi calculado — desconhecido, nunca zero.

Assinar e cancelar não são expostos via MCP, de propósito. Comprometer uma agência a um termo, ou encerrá-lo antes do prazo, é uma decisão comercial com uma contraparte — a mesma razão pela qual o fechamento de faturas e a resolução de achados ficam fora da superfície da ferramenta. Ambos vivem no dashboard.

Controle de acesso: ambas as leituras precisam de attribution_reports, que é gratuito desde P2.6.

Interações (`actuals`) — chave de desenvolvedor

O mesmo dinheiro no grão da tarefa. Uma chamada, SMS ou job com cada perna de fornecedor unida em uma única linha — o grão que sabe quanto tempo o trabalho levou e, portanto, o único que pode declarar custo por minuto. Registrado no grupo actuals, ao lado das leituras por perna acima.

Ferramenta	Descrição
`list_interactions`	Uma linha por tarefa: duração, os fornecedores envolvidos, um detalhamento por tipo de perna e `topKind` nomeando o tipo mais caro. `order_by="cost"` fornece a lista de outliers — as chamadas que estão consumindo a margem
`get_interaction`	Uma tarefa aberta — cada perna em ordem cronológica com fornecedor, tipo de perna, unidades tipadas, fonte de captura, status e custo, além dos identificadores pelos quais as pernas foram unidas
`get_interaction_cost_rollup`	Custo de tarefa por cliente, campanha, agente, canal, resultado ou tipo de tarefa, com custo por minuto por linha

Resultados (`outcomes`) — chave de agente para emitir, chave de desenvolvedor para ler

O que uma tarefa produziu, vinculado à chamada em que seus custos estão. Unido ao custo dessa chamada, é isso que torna o custo por resultado um número em vez de uma estimativa.

Ferramenta	Descrição
`emit_outcome`	Chave de agente. Relate um resultado cobrável contra um id de tarefa; a Floe o resolve para a chamada e vincula a reivindicação lá. Um id de tarefa que não nomeia nenhuma chamada é recusado em vez de armazenado sem vínculo
`list_outcomes`	Encontre reivindicações pela chamada — tarefa, interação, cliente, campanha, tipo, status, fonte. Apenas cabeças de cadeia; uma reivindicação que não pode ser vinculada retorna com um motivo em vez de ser descartada
`get_outcome`	Uma reivindicação com a cadeia que ela corrigiu. Nomear qualquer evento em uma cadeia responde com a cabeça atual e relata `isHead`, então um id salvo antes de uma confirmação ainda resolve

Uma chave de agente só pode relatar. Não há argumento status em emit_outcome: confirmar uma reivindicação, anulá-la, revertê-la e resolver uma colisão são atos de operador na superfície de desenvolvedor, porque movem dinheiro e a evidência que os justifica chega ao backend muito depois da chamada. Esses veredictos são deliberadamente não expostos via MCP.

Por que a reversão fica fora do MCP. Reverter um resultado cobrado escreve uma linha de crédito na próxima fatura do cliente. Essa é uma decisão de operador humano, não algo que um agente deva tomar, e fica ao lado das escritas na tabela de preços, que o MCP também não expõe. Operadores revertem pelo dashboard, pela API de desenvolvedor (POST /v1/developer/outcomes/{eventId}/reverse) ou pela CLI (floe outcomes reverse).

Três tipos podem ser precificados. resolution, meeting_booked e qualified_lead são unidades da tabela de preços: uma reivindicação confirmada de um desses tipos é cobrada no período em que foi confirmada. Todo outro tipo permanece como texto livre: registrado e legível, nunca cobrado.

Documentação (`docs`) — sem chave

Ferramenta	Descrição
`search_floe_docs`	Pesquise o índice de documentação da Floe (llms.txt) — títulos, URLs, descrições

Ferramentas de leitura (`lending`)

Ferramenta	Descrição
`get_markets`	Liste mercados de empréstimo ativos com taxas e liquidez (sem chave)
`get_open_lend_intents`	Navegue pelas ofertas de empréstimo disponíveis para tomar emprestado
`get_open_borrow_intents`	Navegue pelas solicitações de empréstimo de tomadores buscando credores
`get_intent_details`	Obtenha detalhes completos de uma intenção específica por hash
`get_loan`	Obtenha detalhes de empréstimo por ID numérico
`get_user_loans`	Obtenha todos os empréstimos de uma carteira (tomador + credor)
`get_loan_health`	Verifique LTV do empréstimo, status de saúde, risco de liquidação
`get_token_price`	Preço atual do oráculo para tokens de garantia
`get_wallet_balance`	Saldos de tokens de uma carteira
`get_accrued_interest`	Juros acumulados em um empréstimo

Ferramentas de escrita (`lending`, retornam transações não assinadas)

Ferramenta	Descrição
`create_lend_intent`	Crie uma oferta de empréstimo
`create_borrow_intent`	Crie uma solicitação de empréstimo
`create_counter_intent`	Aceite uma oferta existente (o solver combina automaticamente)
`repay_loan`	Quite um empréstimo com proteção contra slippage
`add_collateral`	Adicione garantia para melhorar a saúde do empréstimo
`withdraw_collateral`	Retire garantia excedente
`liquidate_loan`	Liquide um empréstimo não saudável
`revoke_intent`	Cancele uma intenção ativa
`approve_token`	Aprove o gasto de tokens para o protocolo

Ferramentas de análise (`lending`)

Ferramenta	Descrição
`check_compatibility`	Verifique se duas intenções podem se combinar
`calculate_risk`	Métricas de risco: LTV, preço de liquidação, margem
`estimate_interest`	Estimativa de juros para determinados termos de empréstimo

Ferramentas utilitárias (`lending`)

Ferramenta	Descrição
`simulate_transaction`	Simule uma transação (eth_call)
`broadcast_transaction`	Envie uma transação assinada
`get_transaction_status`	Verifique o recibo da transação

Ferramentas de consciência do agente (`spend`) ⭐

Permite que um agente responda "tenho crédito?", "essa chamada vale a pena?" e "onde estou no ciclo de vida do empréstimo?" antes de comprometer capital. Todas exigem uma chave de API de agente (floe_*). A identidade chamadora é obtida do cabeçalho Bearer no modo HTTP, ou de FLOE_API_KEY no modo stdio.

Ferramenta	Descrição
`get_credit_remaining`	Crédito disponível atual, margem para auto-empréstimo, utilização em bps
`get_loan_state`	Estado grosseiro: `idle` \| `borrowing` \| `at_limit` \| `repaying`
`get_spend_limit`	Teto de gasto da sessão ativa atual, se houver
`set_spend_limit`	Defina um teto de USDC em nível de sessão (reinicia a janela da sessão)
`clear_spend_limit`	Remova o teto de gasto da sessão
`list_credit_thresholds`	Liste os limites registrados de utilização de crédito
`register_credit_threshold`	Registre um gatilho de webhook em um limite de utilização (máx.: 20 por agente)
`delete_credit_threshold`	Remova um limite registrado
`get_agent_reputation`	Pontuação de crédito de 0–100, faixa e multiplicador de garantia para o agente chamador

Ferramentas de lista de permissão de comerciante (`spend`)

Opt-in, restrição padrão de negação sobre quais destinos o agente pode pagar. Uma entrada de lista de permissão é uma linha de política comum com teto que também funciona como "permitido E com teto". Modo padrão off = permitir qualquer fornecedor (zero atrito de integração). Todas exigem uma chave de API de agente (floe_*).

Ferramenta	Descrição
`set_allowlist_mode`	Defina a aplicação: `off` \| `host` (bloquear hosts não listados antes da busca) \| `vendor` (bloquear beneficiários não listados antes da assinatura) \| `both`
`get_allowlist_mode`	Leia o modo de aplicação atual do agente
`add_allowlist_entry`	Adicione uma entrada permitida-E-com-teto — `kind=api` (host) ou `kind=vendor` (beneficiário), com um teto de gasto `limit_raw`
`remove_allowlist_entry`	Revogue uma entrada da lista de permissão por id de política (de `list_allowlist`)
`list_allowlist`	Liste as entradas da lista de permissão de host (`api`) e beneficiário (`vendor`) com seus tetos

Ferramentas de gateway de inferência (`pricing`)

Ferramenta	Descrição
`list_models`	Catálogo de modelos compatível com OpenAI para Floe Inference (texto/embedding/TTS/STT/realtime)
`estimate_inference_cost`	Precifique uma chamada de inferência a partir de um vetor de uso sem fazê-la

Habilidade de consciência de orçamento

As habilidades de agente da Floe vivem em seu próprio repositório: Floe-Labs/agent-skills.

A habilidade floe é o manual que transforma as ferramentas MCP acima em comportamento deliberado de gasto: leia o status do orçamento antes de pagar, reduza conforme se aproxima do teto mais apertado, replaneje para terminar a tarefa dentro do orçamento e pare antes do teto. Ela lê o status das ferramentas existentes get_credit_remaining, get_spend_limit, estimate_x402_cost e get_loan_state, além do cabeçalho X-Floe-Budget-Advisory que o proxy x402 da Floe carimba nas respostas pagas — sem nova ferramenta ou backend necessário.

Sinal suave, não a salvaguarda. A habilidade ajuda um agente cooperativo a gastar com sabedoria. O teto real é aplicado no lado do servidor — a linha de crédito on-chain, o teto de gasto da sessão e (se configurada) a lista de permissão de comerciante recusam chamadas além do limite, independentemente do que o agente decidir.

Instalação:

npx skills add floe-labs/agent-skills          # skills.sh CLI
# or manually:
git clone https://github.com/floe-labs/agent-skills
cp -r agent-skills/skills/floe ~/.claude/skills/   # or .claude/skills/ per-project

Fluxo de transação

Todas as ferramentas de escrita retornam transações não assinadas — o servidor nunca detém chaves privadas.

1. Call a write tool (e.g., create_counter_intent)
   → Returns { transactions: [...], summary, warnings, expiresAt }

2. (Optional) Call simulate_transaction to dry-run

3. Sign each transaction locally with your wallet

4. Call broadcast_transaction with the signed hex
   → Returns { transactionHash, status, blockNumber }

Exemplo: Obtenha uma linha de crédito USDC

Agent: "I need 9,950 USDC working capital"

1. get_open_lend_intents → browse USDC/USDC offers
2. create_counter_intent(offer_hash, wallet) → unsigned txs
3. simulate_transaction(from, to, data) → { success: true, gasEstimate }
4. Sign locally → signed hex
5. broadcast_transaction(signed_hex) → confirmed

Assinatura com viem

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const wallet = createWalletClient({
  account: privateKeyToAccount(PRIVATE_KEY),
  chain: base,
  transport: http(),
});

// Sign and send each transaction in order
for (const { transaction: tx } of response.transactions) {
  const hash = await wallet.sendTransaction({
    to: tx.to,
    data: tx.data,
    value: BigInt(tx.value),
  });
  // Wait for confirmation before next step
}

Uso programático

SDK de cliente MCP

import { Client } from "@modelcontextprotocol/sdk/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-agent" });
await client.connect(new StreamableHTTPClientTransport(
  new URL("https://mcp.floelabs.xyz/mcp"),
  { requestInit: { headers: { "Authorization": "Bearer floe_..." } } }
));

const markets = await client.callTool("get_markets", {});
const counter = await client.callTool("create_counter_intent", {
  offer_hash: "0x...",
  wallet_address: "0x...",
});

LangChain / LangGraph

from langchain_mcp_adapters import MultiServerMCPClient

async with MultiServerMCPClient({
    "floe": {"url": "https://mcp.floelabs.xyz/mcp", "headers": {"Authorization": "Bearer floe_..."}}
}) as client:
    tools = client.get_tools()
    # Use tools in your agent

CrewAI

Agentes CrewAI podem consumir as ferramentas MCP da Floe via langchain-mcp-adapters. Uma crew executável está disponível em floe-cookbook/crewai-demo.

Arquitetura

Your Agent → MCP Server → credit-api.floelabs.xyz → Envio Indexer / Base RPC
                ↑                    ↑
           This package         Private backend
          (open source)        (holds secrets)

O servidor MCP é um cliente HTTP leve. Toda a lógica de protocolo, consultas de indexador e chamadas RPC acontecem no backend privado da API Floe. Este pacote contém apenas definições de ferramentas e chamadas fetch().

Protocolo de empréstimo (avançado)

A Floe é a camada de gastos para agentes de IA — uma chave que paga qualquer API de fornecedor sob orçamentos programáveis (tudo acima). Ela também expõe uma camada avançada de empréstimo baseada em intenções e nativa de cripto na Base, para agentes que desejam capital de giro contra depósitos:

Mercado primário (USDC/USDC): Deposite USDC como garantia e tome emprestado até 99,5% como linha de crédito. Sem risco de volatilidade de preço — mercado de mesmo token.
Mercados voláteis: Também suporta garantias em WETH e cbBTC para casos de uso nativos de cripto.
Solvers combinam automaticamente pares de intenções compatíveis on-chain.
Empréstimos são criados com termos correspondentes, com garantia bloqueada em escrow isolado por empréstimo.
Sem custo de gás — a Floe patrocina todos os custos de transação.
Taxas fixas — sem surpresas de taxas variáveis.

Conceitos-chave:

Intenção: Uma oferta on-chain para emprestar ou tomar emprestado
Contra-Intenção: Uma intenção criada para corresponder a uma oferta existente
Fator de Saúde: Proporção entre o valor da garantia e a dívida — abaixo do limite, aciona a liquidação
LTV (Loan-to-Value): Dívida do tomador como % do valor da garantia

Endereços dos Contratos (Base Mainnet)

Contrato	Endereço
LendingIntentMatcher	`0x17946cD3e180f82e632805e5549EC913330Bb175`
PriceOracle	`0xEA058a06b54dce078567f9aa4dBBE82a100210Cc`
LendingViews	`0x9101027166bE205105a9E0c68d6F14f21f6c5003`
x402 Facilitator	`0x58EDdE022FFDAD3Fb0Fb0E7D51eb05AaF66a31f1`

Licença

MIT