Why payroll is the missing layer for personal finance agents

A personal finance agent that only reads bank transactions is working downstream of the most important number in a household budget: the paycheck. By the time money lands in a checking account, the decisions that shape a person's savings rate have already been made inside their payroll account — gross pay, taxes, 401(k) deferrals, and how net pay is split across accounts.

Solving problems like this is why I joined Pinwheel as CTO. Pinwheel has the ability to give AI agents access to that upstream layer. With a user's permission, an agent can read verified income and employment data straight from payroll, and it can change where the paycheck goes. At Pinwheel we describe this as sitting upstream of the paycheck, with the ability to control where money flows rather than only report where it went. This is where the most meaningful value can be delivered to consumers. And it’s here that my team at Pinwheel is creating the future of finance. 

This post is for engineers, researchers and product leads at frontier AI labs and large platforms building consumer personal financial management (PFM) agents: tool-using models that read a user's financial state and take scoped actions on it. For AI builders, the hard problem isn't model capability. It's finding data and action partners whose access is consumer-permissioned, auditable, compliant with consumer-finance law, and resistant to fraud. This post outlines the four capabilities we expect AI builders of agentic PFM experiences to need in the near term:

  • Payroll Insights: a read action that exposes a consumer's historical and projected income streams, so an agent can compare their earnings, savings rate and investment rate against their goals.
  • Direct deposit allocations: a write action that lets a consumer permission the agent to raise savings and investment contributions by adjusting how each paycheck is split.
  • Tax forms: W-2s, 1099s and 1040s from the source, in structured JSON, for filing prep, quarterly estimates and withholding optimization.
  • Earned Wage Access: using projected paychecks and shift-level earnings to spot a shortfall and, with approval, access wages the user has already earned.

Each capability is evaluated below on the criteria a lab's security, legal and trust-and-safety reviewers will apply: where the data originates, how consent is captured and revoked, which regulatory regime governs it, what the attack surface looks like when a model is in the loop, and how writes are verified.


What is Pinwheel?

A personal finance agent is an AI assistant that manages money on a consumer’s behalf. It goes beyond answering questions to take actions, such as adjusting a paycheck split or gathering tax forms. Agents are already unburdening consumers from the friction of scheduling, reservations, reminders, and travel planning. Personal finance is next.

Pinwheel is a payroll connectivity API that lets consumers permission an application to read their payroll data and update their direct deposit settings. It connects to 1,800+ payroll providers and employer platforms, plus 40+ time-and-attendance systems, through one integration and one normalized data model. 

The Pinwheel developer docs describe a consent-first, asynchronous flow. Your server mints a short-lived link token scoped to specific jobs; the client SDK (web, iOS, Android, React Native) launches Pinwheel Link; the user authenticates directly with their payroll platform; Pinwheel creates an account object and executes the requested jobs; and signed webhooks notify your server when results are ready to fetch over REST. The API secret stays server-side, requests are pinned with a version header, and a sandbox mode returns mock data with no live payroll writes. The underlying jobs an agent can draw on are:

JobRead or writeWhat it gives a PFM agent
paystubsReadItemized pay history: gross, net, taxes, deductions
incomeReadAnnual salary or hourly wage
employmentReadEmployer name, start date, status
shiftsReadHours and earnings for hourly and gig work
identityReadName and date of birth for the payroll account owner
direct_deposit_allocationsReadCurrent paycheck split across destination accounts
direct_deposit_switchWriteChanges the split, in part or in full, to a specified account
Source: Pinwheel developer documentation. Pinwheel also offers W-2 and 1099 retrieval, bill switching and subscription management through the same account and webhook model.

Pinwheel also offers W-2 and 1099 retrieval, bill switching and subscription management through the same account and webhook model.

‍

Compliance and fraud posture

For a lab evaluating partners, the relevant question is how each property reduces risk once a model is orchestrating calls:

PropertyWhat it means for a PFM agent
Consumer-permissioned accessThe user authorizes each connection in Pinwheel Link; your app only receives the jobs it requested and the user granted.
Source-of-truth dataIncome and paystubs come from the payroll system that issued them, not from uploaded PDFs or screenshots that can be edited or fabricated.
FCRA consumer reporting agencyConsumers can see the data shared about them and dispute errors; customers can use the data for FCRA-permissible purposes such as credit decisions.
SOC 2 Type 2 and ISO 27001Independently audited security controls; PCI DSS Level 2 compliance.
Credential-less authentication (PreMatch)Secure identification of matching user payroll records from within an authenticated financial account, e.g., online banking. Pinwheel compliantly writes actions with a one-time passcode.
Read-back on writesAllocation changes are confirmed from payroll, so a write is verified rather than assumed.

No provider eliminates fraud. Payroll-sourced, consumer-permissioned data removes the most common vectors in income workflows, document tampering and self-reported income, and narrows what an attacker can exploit.


Get Payroll Insights: historical and projected income streams

Get Payroll Insights gives an agent one answer to the question every financial plan starts with: how much does this person earn, how reliably, and what will they earn next? It draws on verified payroll data rather than inferring income from bank deposits.

Bank-transaction income inference is a lossy, adversarially weak signal. It can't see gross pay, pre-tax deductions or employer retirement contributions. It often confuses transfers with wages, and it misses income routed to other accounts. Payroll-sourced data closes those gaps because it comes from the system that generated the paycheck.

What the agent learns about past income

  • Gross-to-net breakdown per pay period: earnings, taxes, benefits and retirement deferrals, itemized from paystubs.
  • Every income stream: multiple employers, salaried and hourly jobs, and gig work, each with its own pay frequency.
  • Variability: overtime, bonuses, commissions and shift-level hours for workers whose pay changes week to week.
  • Trajectory: raises, job changes and gaps, dated from employment records.

What the agent can project about future income

With pay history, pay frequency and current rate, an agent can build a forward income calendar: the expected date and amount of each upcoming paycheck. For hourly and gig workers, Pinwheel's shift data supports accrued-earnings calculations, so the agent knows what has already been earned but not yet paid.

That forecast changes what an agent can say. Instead of "you spent more than usual this month," it can say "your next two paychecks are expected to total $4,180, your rent and car payment take $2,050, and you can safely move $400 more to savings this cycle."

Implementation notes for model-driven use

  • Compute deterministically, reason with the model. Pay-frequency detection, annualization, rate calculations and forecasts belong in code. Hand the model a typed, structured result so it explains and plans rather than doing arithmetic over raw paystubs.
  • Keep provenance on every field. Tag each value as payroll-sourced, derived or user-entered, so the model can state its confidence and your evals can catch fabricated figures.
  • Model forecast uncertainty. Salaried pay is near-deterministic; hourly, commission and gig income need ranges. Return a low, expected and high value per future pay date rather than a single number.
  • Refresh on events, not polls. Use webhooks and recurring-access monitoring to update state when a new paystub posts, keeping the agent's context current without redundant calls.
  • Minimize data in context. Pass the model aggregates and the fields a task needs, not full paystub payloads with identifiers it doesn't use.

Because the data comes from the issuing payroll system, the agent has the primary source of income data. The identity job also lets you match the payroll account owner against your own KYC record, which helps catch an account linked to someone else's payroll.

‍

Comparing earnings, savings and investment rates against goals

Payroll data lets an agent measure a savings rate correctly, because it sees money saved before it ever reaches a bank account. A user contributing 6% to a 401(k) and splitting $200 per paycheck to a brokerage account has a real savings rate that bank data alone would understate.

With Get Payroll Insights, an agent can compute and track:

MetricHow payroll data improves it
Earnings rateGross and net pay per period and annualized, across every employer
Deductions rateVerify deductions are set correctly for the employee’s earning profile
Savings ratePre-tax deferrals plus paycheck splits to savings accounts, as a share of gross pay
Investment rate401(k), 403(b) and HSA deferrals plus splits to brokerage accounts
Goal paceProjected contributions per paycheck against a target amount and date

With these connections, a user can then set a recurring task to check their payroll automatically and inform them of any anomalies. The same data supports peer and benchmark comparisons. An agent can place a user's savings rate against their own history, a recommended target such as 15% of gross income for retirement, or, where paystubs itemize it, the employer match they are leaving unclaimed.
‍

Acting on the user's behalf: adjusting direct deposit to save and invest more

The most valuable thing a PFM agent can do is close the gap between a plan and behavior. Pinwheel's direct deposit write action does that at the source: with the user's permission, the agent changes how each paycheck is split, so savings and investing happen before the money can be spent.

Pinwheel's allocation model supports multiple destination accounts per paycheck. Each destination gets a fixed amount, a percentage, or the remainder, funded in priority order. That maps directly onto common goals:

  • Send 10% of every paycheck to a high-yield savings account until the emergency fund is full.
  • Route a fixed $150 per paycheck to a brokerage account for monthly index fund purchases.
  • Raise the savings split by 1 percentage point after each raise, so lifestyle creep never starts.
  • Leave the remainder in checking to cover bills.

After the change, the agent reads direct_deposit_allocations back from payroll to confirm the new split is active, rather than assuming the write succeeded. The next paystub then verifies that money actually moved.

Direct deposit diversion is a known fraud pattern that must be defended against in any agentic product design. Attackers take over accounts and attempt to redirect the victim's paycheck to an account they control. The LLM design answer is to constrain the write path, not avoid it. Pinwheel restricts destinations to accounts verified as owned by the same person. We will also require stepped-up authentication for any change to a destination, and send an out-of-band notice whenever an allocation changes.

‍

Solving cash-flow gaps with Earned Wage Access

The same payroll data that powers savings goals also lets an agent spot a cash-flow gap before it becomes an overdraft or a late fee, and resolve it with wages the user has already earned. Earned Wage Access (EWA) lets a worker draw pay they have earned before payday, instead of turning to a payday loan or a high-interest card.

Sizing a safe amount

Pinwheel's shifts data returns shift-level hours and itemized earnings, which EWA providers use to calculate how much a user has earned but not yet been paid. That covers hourly, overtime and gig work, so the agent can serve variable-income workers who most often face timing gaps. Size advances against net accrued earnings, after estimated taxes, benefits and existing allocations, and recommend only what closes the gap, never the full accrued balance. Because accruals are computed from verified shifts rather than user claims, advances are harder to obtain against work that never happened.

Identifying options and accessing funds

The agent can compare the ways a user could cover the gap and present them side by side:

  • Employer-sponsored EWA, where the user's employer offers it as a benefit, often at the lowest cost.
  • Direct-to-consumer EWA apps, which advance earned wages and recover them from the next paycheck.
  • Lower-cost alternatives, such as moving money from savings, shifting a bill's due date, or a smaller advance.

For each option the agent shows the amount available, every fee or expected tip, when funds arrive, and how repayment works. Once the user picks one, the agent can start the request and, where the provider supports it, set up repayment from the next paycheck through a direct deposit allocation. Pinwheel supports this paycheck-linked repayment for EWA and pay-by-paycheck products.

Guardrails specific to EWA

EWA can help in a pinch and hurt when it becomes routine, because each advance shrinks the next paycheck. An agent should:

  • Require explicit approval for every advance and show the total cost in dollars.
  • Prefer free options, such as savings or bill rescheduling, when they cover the gap.
  • Watch for repeated advances and shift the conversation toward rebuilding a buffer, using the savings tools above.
  • Follow the EWA rules in the user's state, which vary and continue to change.

The goal is an agent that bridges a short gap once and then helps make sure the user doesn't face the same gap next month.

‍

Taxes: source-of-truth tax forms for filing, estimates and withholding

Tax data closes the loop between what a user earns and what they keep. Pinwheel Taxes retrieves a user's tax forms directly from their payroll or income platform, so an agent works from issued documents rather than uploads or hand-typed boxes.

What the API returns

The tax_forms job pulls documents from the connected account. Your server is notified through a tax_forms.added webhook and fetches results through the List tax forms and Get tax form endpoints. Forms come back as both PDF and structured JSON. Supported types include W-2, 1099-K, 1099-MISC and 1099-NEC, plus 1040s from tax platforms.

The JSON format is what matters for agents. A model can reason over typed fields, such as wages, federal and state withholding, and payer details, without OCR or document parsing, which removes a common source of extraction errors and hallucinated figures.

What a PFM agent can do with it:
Use caseHow the agent applies tax data
Tax filing prepPre-populate a return or hand structured forms to a filing partner, with no uploads or manual entry.
Estimated taxes for 1099 earnersUse last year’s 1099s and this year’s shift and paystub data to project quarterly payments, then reserve the amount through a direct deposit split to a tax savings account.
Withholding optimizationCompare year-to-date withholding on paystubs with projected liability, flag over- or under-withholding, and recommend a W-4 change.
Annual income verificationVerify total earnings, payer details and taxes withheld for a full year, complementing pay-period data.
Pinwheel’s documented write action is the direct deposit change; a recommended W-4 adjustment is something the user submits through their employer’s payroll or HR system.

The estimated-tax flow shows how the capabilities combine: tax forms set the baseline, Get Payroll Insights projects this year's income, and an approved direct deposit allocation sets the reserve aside automatically each paycheck. Pinwheel's documented write action is the direct deposit change; a recommended W-4 adjustment is something the user submits through their employer's payroll or HR system.

Compliance and fraud notes

Tax forms pulled from the issuing platform are much harder to falsify than uploaded PDFs, which makes them a strong verification signal for agents that underwrite or verify income. Tax documents are also among the most sensitive data a user shares: request the tax_forms job only for features that need it, keep full SSNs and taxpayer IDs out of model context, and pass the model only the fields a task uses. An agent should present tax estimates as estimates and point users to a tax professional for complex situations.

‍

Reference architecture: the paycheck-to-goal loop

A PFM agent built on Pinwheel runs a closed loop: read income, compare it to goals, propose a change, get approval, write the change, and verify it on the next paycheck.

  1. User consents
    Pinwheel Link connects their payroll account
  2. Get Payroll Insights
    Past and projected income, savings and investment rates
  3. Agent checks goals
    Compares rates to targets, checks the cash-flow floor
    proposes a split
  4. User approves change
    Sees current vs. proposed split per paycheck
  5. Pinwheel updates split
    Direct deposit allocation changed at the payroll source
    verified by read-back, then the next paystub
Back to Get Payroll Insights: verified by read-back, then the next paystub
  • Read action
  • Write action

PFM agent loop · one read action, one write action

The read side runs continuously; the write side runs only when the user approves. Each new paystub feeds the next pass, so the agent keeps savings and investment rates on pace as income changes.

Example: exposing the actions as agent tools

Most teams wrap Pinwheel calls in their own tool layer, exposed through function calling or an internal MCP server, so the model sees a small, typed, least-privilege interface. The definitions below are illustrative, not Pinwheel's API schema:

agent_tools.json
1[
2 {
3 "name": "get_payroll_insights",
4 "description": "Return the user's verified historical and projected income by stream, plus current earnings, savings and investment rates from payroll.",
5 "input_schema": {
6 "type": "object",
7 "properties": {
8 "months_history": {
9 "type": "integer"
10 },
11 "months_forecast": {
12 "type": "integer"
13 }
14 }
15 }
16 },
17 {
18 "name": "propose_deposit_allocation",
19 "description": "Draft a new paycheck split toward a goal. Does not change anything; returns a proposal for the user to approve.",
20 "input_schema": {
21 "type": "object",
22 "properties": {
23 "goal_id": {
24 "type": "string"
25 },
26 "allocations": {
27 "type": "array"
28 }
29 },
30 "required": [
31 "goal_id",
32 "allocations"
33 ]
34 }
35 }
36]

The actual write runs only from your application after the user approves the proposal in your UI. Keeping the model's tools to read and propose means no prompt, however crafted, can move a paycheck on its own.

‍

Threat model and controls for paycheck-moving agents

Putting a model in the loop of a financial write adds attack surface that traditional fintech flows don't have. Pinwheel's consent and verification model covers the provider side; the agent layer needs its own controls, mapped to specific threats:

ThreatControl
Prompt injection via emails, documents, transaction memos or merchant namesThe model can only call read and propose tools; executing a write requires a user approval event in your UI, outside the model’s control.
Confused deputy: the agent acts on instructions that didn’t come from the userBind every write to an authenticated user session and a signed approval record; never execute writes from autonomous background runs.
Account takeover leading to paycheck diversionDestination allowlist of ownership-verified accounts, step-up authentication on destination changes, out-of-band notifications.
Over-aggressive savings causing overdraftsCash-flow floor checked against projected net pay and recurring bills; per-change and per-period limits on allocation deltas.
Duplicate or partial executionIdempotency keys on write requests; reconcile state from webhooks and read-back before retrying.
Spoofed callbacksVerify webhook signatures before acting on any job result.
Silent drift between intended and actual stateRead back allocations after each write, then confirm the first paycheck under the new split.
Over-broad data accessRequest only the jobs a feature needs in each link token; keep identifiers out of model context.

Every change should also be reversible in one step and logged with the goal, the approval, the model's proposal and the before-and-after allocations. That audit trail is what lets a lab's trust-and-safety team, a bank partner or a regulator reconstruct exactly why money moved.

‍

FAQ for AI builders