Billing

Swirls bills your organization on a credit model. Two meters cover everything that runs: execution credits for the work your workflows and agents do, and tool spend for the paid external capabilities your agents buy through their wallet. Plans set the included amounts; one-time top-ups extend them. Usage is reported per project so you can see which project spent what.

For current plans, prices, and per-node credit numbers, see swirls.ai/pricing. This page covers the mechanism.

The two meters

The meters are independent. An agent turn that pays for an external tool consumes both: the flat turn cost in credits, and the tool's price from the tool-spend balance.

Execution credits

Workflow runs

Each successful node execution spends credits. The cost depends on the node type:

• AI, agent, and vendor-backed nodes (scrape, parallel, disk) cost the most.
• Email and stream nodes sit in the middle.
• Plumbing nodes (code, http, postgres, database, bucket, integration, nested workflow) cost the least.
• Pure control flow (map, while, switch, wait) is free. The work it orchestrates is what gets billed.

Failed nodes are not billed. The current per-node numbers are on swirls.ai/pricing.

Agent turns

Talking to an agent directly bills a flat credit cost per turn, where a turn is one message you send. The charge lands once, at the conversation entry point: sub-agent delegation and tool calls inside the turn do not multiply it. Turns that do not complete are not billed.

Enforcement

The pattern is check, execute, track:

• Workflow runs check your credit balance before starting. When credits are exhausted, the run is parked on a billing hold instead of failing. The Billing page shows a banner with the held count; topping up or upgrading releases held work.
• Agent turns are rejected up front when credits are exhausted. The API returns HTTP 402 with code insufficient_credits, and the agent stops accepting new turns until your balance recovers.

Agent tool spend and the wallet: budget

Agents pay for external capabilities through a per-agent wallet declared in the .swirls file:

agent poem_writer {
  ...
  wallet: {
    budget: 10       // USD per cadence window
    cadence: daily   // daily | weekly | monthly
    maxPerCall: 2    // optional USD ceiling per tool call
  }
}

budget caps what the agent may spend per cadence window. maxPerCall caps any single tool call; when omitted, a platform default applies. Declaring wallet: is what enables the paid external tools for that agent. See the wallet block for the agent-side details.

Enforcement is two-layer, and both layers return HTTP 402 when exceeded:

1. The agent's cadence budget. Spend is reserved before a paid call and settled after it. Exceeding the window's budget fails the call with agent_wallet_exceeded, and the agent's wallet stays closed until the window resets.
2. The organization's tool-spend balance. Every agent draws from the org-wide prepaid balance. When it is exhausted, paid calls fail with insufficient_tool_budget until you top up.

Plans and top-ups

• Free is inspection-only: author, deploy, and inspect, with no execution credits.
• Paid self-serve plans include a monthly credit allowance plus usage-based overage per credit. Larger plans include more credits at a lower overage rate. The entry plan carries a free trial.
• Enterprise removes self-serve limits, adds platform-managed vendor keys, and is billed by your account team rather than self-serve checkout.

One-time top-ups are available on any paid plan: credit packs add execution credits, and tool budget packs add tool spend. Top-ups land on your balance right away.

Plan changes, top-up purchases, invoices, and payment details are all managed on the Billing page in the Portal.

Where to see usage

The Billing page

Billing in the Portal, at the organization level, shows:

• Your current plan, credits used this cycle, credit balance including top-ups, and tool budget balance.
• A billing-hold banner when runs are parked, with the held count.
• Credit usage by project, and tool spend by project and by agent, over a selectable range.
• Plan cards, top-up purchases, your invoices, and subscription management.

Each agent's detail panel also shows its wallet status: the window's budget, what is spent, what is reserved, and what remains.

The SDK

The billing client reads the same numbers programmatically:

Plan changes and payment are not SDK operations. They run through the Billing page.

Next steps

• swirls.ai/pricing: current plans, prices, and per-node credit numbers.
• Agents: the wallet: block and the paid tool catalog.
• SDK billing client: usage queries from your own code.