Account Insights

Account Insights answers two questions for a customer: “how is my account doing?” and “what should I do about it?” — as data your UI can render directly, and as answers the payment agent gives in conversation.

GET /customers/{customer_id}/insights — a computed report: a snapshot of balances and obligations, observations about recent activity, and advisory suggestions. No LLM anywhere in this path — every number, date, and sentence is computed deterministically from the customer’s own objects.
The drafting conversation — ask the payment agent about the account in the same conversation that drafts payments, and it narrates the same deterministic data. See Asking about the account.

Beta — part of the agentic early-access surface. The report is read-only by construction: it cannot move money, create, or change anything.

POST /customers/{customer_id}/insights/chat has been removed. The standalone advisory chat is gone; its Q&A now happens inside the drafting conversation, which has the account in front of it. If you called it, see Asking about the account for the replacement.

The report

The report is a view, not a stored object — computed on demand from the customer’s scheduled payments, mandates, recipients, wallets, and balances. There is nothing to create, poll into existence, or clean up.

curl https://api.platform.dakota.xyz/customers/2vWxCustomer0000000000000000/insights \
  -H "X-API-Key: $DAKOTA_API_KEY"

{
  "customer_id": "2vWxCustomer0000000000000000",
  "generated_at": 1783075200,
  "snapshot": {
    "total_usd": "3100.25",
    "balances": [
      { "wallet_id": "2vWxWallet000000000000000000", "name": "Operating",
        "network_id": "base-mainnet", "asset": "USDC", "amount_usd": "3100.25" }
    ],
    "upcoming": { "days": 14, "count": 3, "totals": { "USDC": "5200" } },
    "open_scheduled_payments": 5,
    "active_mandates": 2
  },
  "insights": [
    {
      "kind": "upcoming_payments",
      "severity": "info",
      "message": "3 payment(s) scheduled in the next 14 days (5200 USDC).",
      "detail": { "count": 3, "window_days": 14 },
      "evidence": [ { "type": "scheduled_payment", "id": "2vWxPayment00000000000000000" } ]
    }
  ],
  "suggestions": [
    {
      "kind": "funding_shortfall",
      "severity": "critical",
      "message": "A funding wallet shows $3100.25 of USDC but 5200 USDC of payments fire from it on base-mainnet in the next 7 days — top up at least ~2099.75 USDC by 2026-07-14 or 3 payment(s) may fail.",
      "detail": { "wallet_id": "2vWxWallet000000000000000000", "shortfall_estimate": "2099.75" },
      "evidence": [
        { "type": "wallet", "id": "2vWxWallet000000000000000000" },
        { "type": "scheduled_payment", "id": "2vWxPayment00000000000000000" }
      ]
    }
  ]
}

Three parts:

snapshot — typed facts for stat cards: per-wallet balances (aggregated over all the customer’s linked wallets), upcoming-payment totals per asset, open/active counts.
insights[] — observations: what is happening.
suggestions[] — advice: what the customer may want to do. Always advisory — acting on one is a separate, human-gated step through the normal payment flow.

Both arrays share one item schema: {kind, severity, message, detail, evidence}.

Rendering items

severity is a closed set: info | warn | critical. Sort and color by it.
kind is an open set — new kinds appear over time without a breaking change. Render an unrecognized kind generically from message + severity; never drop it.
message is a complete, human-readable sentence. A minimal UI can show messages alone and be correct.
detail carries the raw computed values behind the sentence, for custom rendering.
evidence[] contains typed references ({type, id} — wallet, scheduled_payment, mandate, recipient; up to 10 per item) to the exact objects the item was computed from — deep-link each claim to the data behind it. evidence.type is open-set like kind.

The kind catalog

kind	array	severity	fires when
`upcoming_payments`	insights	info	open payments due within the next 14 days (count + per-asset totals)
`payment_failures_clustered`	insights	warn	≥2 recent failures to the same payee sharing one reason — the likely root cause, surfaced once
`payments_failed`	insights	info	remaining recent singleton failures
`account_activity`	insights	info	executed volume over the last 30 days + mandates awaiting signature
`new_counterparty`	insights	info	open payments to a recently added payee
`counterparty_concentration`	insights	info	one payee dominates recent executed outflow
`payment_at_risk`	suggestions	warn	open payments already past their scheduled time
`funding_shortfall`	suggestions	critical	a funding wallet’s balance is below what fires from it in the next 7 days — includes the estimated top-up and deadline
`mandate_expiring`	suggestions	warn / info	an active mandate ends within 14 days — `warn` if open payments depend on it
`mandate_headroom`	suggestions	critical / warn	a mandate window cannot cover what’s planned (`critical` — the excess will be denied at fire time) or is ≥80% consumed (`warn`)

A mandate that is exactly on plan — filled by its own scheduled series — stays silent; headroom items fire only on breach or tightness.

Degradation, not errors

A deployment without a balance index simply omits balance-derived parts (snapshot balances, shortfall math); the rest of the report still computes. Missing data degrades the report — it never 500s.

Asking about the account

There is no separate chat endpoint. A customer asks about the account in the same conversation that drafts payments — POST /payment-agents/{payment_agent_id}/proposals, documented in the quickstart. “Pay Brightline 2,000 USDC” and “why did my payments to Brightline fail?” are the same call.

curl -X POST https://api.platform.dakota.xyz/payment-agents/2vWxAgent0000000000000000000/proposals \
  -H "X-API-Key: $DAKOTA_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Anything I should know about my account this week?" }
    ]
  }'

A question is answered in reply, and there is no proposals field at all — the key is omitted, not returned as an empty array, because nothing was drafted:

{
  "reply": "You have 3 payments (5200 USDC) due in the next two weeks, and your Operating wallet shows $3100.25 — about 2100 USDC short. Consider topping it up before July 14.",
  "conversation_status": "ok"
}

Branch on presence, not length: proposals is absent whenever the turn drafted nothing, so a client testing proposals.length === 0 will throw rather than take the no-op path. That absence is the safety property, and it is why the two surfaces merged. A question cannot become a payment by being phrased like one: the agent still cannot move money, and anything it does draft arrives as proposals your customer reviews and signs in the normal way.

Enabled per client. Account narration is an admission decision, not a deployment side effect — it is off by default even for clients already using agentic payments. Ask Dakota to enable it. With it off, the drafting conversation is unchanged: same tools, same behaviour, and account questions simply go unanswered.

Why merge them

Splitting them meant your application had to guess, per message, whether the customer was instructing or asking, and route to a different endpoint accordingly. That guess is made from the words alone, before anyone has looked at the account — and it is asymmetric: mistaking a question for an instruction is mild, while mistaking “pay Brightline” for a question silently drops a payment. The agent makes the same decision with the account actually in front of it, and does not have to choose one or the other — a turn can answer a question and draft, which is exactly what “pay MeatCo and tell me how much I’ve spent on them” asks for.

Where the numbers come from

The model never computes facts. It reads them from deterministic, server-computed, read-only tools:

It can read	Which is
the insight report	byte-identical to what `GET .../insights` returns — the conversation and your dashboard can never disagree
recent payments	statuses, amounts, payee names, and human-readable dates, resolved server-side; can narrow to a single agent (“what did the payroll agent spend?“)
mandates	with used/remaining headroom, same math as the fire-time gate

These read the customer’s whole account, not just the conversing agent’s slice of it — the same view GET /customers/{id}/insights already returns — and results say which view they are narrating. None of them can write, and none can be pointed at another customer: they are scoped to the agent’s customer by construction.

Scope and bounds

conversation_status reports how the boundary screen treated the turn:

Value	Meaning
`ok`	a normal turn
`warned`	off-topic; the customer was warned but may continue
`blocked`	the conversation is terminated (repeated off-topic turns, or a manipulation attempt) — stop serving it and offer a fresh one
`rejected_input`	this message was refused wholesale (e.g. more payees than one conversation supports). Do not append it to the history — `reply` explains what to resend, and the conversation itself continues unaffected

Account questions ride the drafting conversation, so they take its caps and budget rather than any chat-specific ones: 200 messages and 512 KB of text per request, 30 drafts/hour and 200/day per customer. See Limits.

Report or conversation?

Render the report — it is structured, deterministic, and cheap, and it needs no LLM. Use the conversation where a customer benefits from asking follow-ups (“why did my payments to Brightline fail?”) — its answers read the same data the report shows, so the two surfaces always agree.

Playground

Documentation

Import Share Tokens

Agentic Payments

Authentication

Developer Tools

Account Insights

The report

Rendering items

The kind catalog

Degradation, not errors

Asking about the account

Why merge them

Where the numbers come from

Scope and bounds

Report or conversation?

​The report

​Rendering items

​The kind catalog

​Degradation, not errors

​Asking about the account

​Why merge them

​Where the numbers come from

​Scope and bounds

​Report or conversation?

The report

Rendering items

The kind catalog

Degradation, not errors

Asking about the account

Why merge them

Where the numbers come from

Scope and bounds

Report or conversation?