Skip to content
CandorHome

Candor developer resources

Build against the finance app your agent operates.

Candor publishes a REST API, an authenticated remote MCP server, a command-line app, and standard Agent Skills. These surfaces share one contract: JSON is canonical, financial reads carry freshness and evidence, writes are idempotent, and every public operation records why it happened.

Access uses OAuth 2.0 with PKCE and scoped credentials. There are no static API keys to copy into a prompt. A user creates their own Candor account, then explicitly approves the agent or CLI that will use it.

Start with the interface your agent supports.

OpenAPI

The machine-readable REST contract, including OAuth, request fields, idempotency, response envelopes, errors, and versioning.

Read Candor OpenAPI

MCP server

The production Streamable HTTP MCP endpoint. It uses OAuth and exposes the same guarded Candor operations through agent-native tools.

Connect to Candor MCP

Agent instructions

The public getting-started skill explains when Candor fits, how to install the right package, and how an agent verifies access.

Read the setup skill

Public package

The source-available Candor Finance package contains the skill and platform manifests used by supported agent runtimes.

Open the package repository

How Candor behaves for your agent.

What Candor does on its own, how it recovers from failure, and what every agent is allowed to do.

What runs without being asked

Candor reviews each workspace on its own soon after its first transactions arrive, then again on a schedule. Nobody has to open a chat for that to happen.

  • The review raises areas worth looking into and gaps worth filling, each pointing at the records behind it, shown on the dashboard and handed to the agent in its next workspace opening.
  • Figures are computed by Candor's code, not by a model, so the same records give the same numbers.

When something fails

Failures surface as data the agent can act on, and background work retries itself.

  • Bank connections: when a bank login expires or access is revoked, Candor marks the connection on its own. The agent gets a warning with the reconnect link, and the next review raises it.
  • Background work: a review that fails retries automatically.
  • API errors: every error carries a code, a message, and whether it is retryable, and many carry the fix. Continuations come back in next_actions.
  • Retries: writes take an Idempotency-Key, which the CLI and MCP server send for you, so a retried request cannot apply twice.
{
  "status": "error",
  "errors": [{
    "code": "insufficient_scope",
    "retryable": false,
    "required_capability": "candor:state.write",
    "message":
    "This OAuth grant requires the candor:state.write scope for this operation.",
    "suggested_command": "candor auth login"
  }],
  "next_actions": [{
    "intent": "reauthorize_oauth_client",
    "command": "auth.login",
    "shell": "candor auth login"
  }]
}

Permissions and the audit trail

Agents work under scoped OAuth grants, and every operation leaves a record.

candor:read
Read financial records and workspace state.
candor:state.write
Save notes, budgets, goals, rules, and corrections inside Candor.
candor:connections
Refresh existing bank connections.
candor:account.manage
Sign-in and billing operations.
  • The user approves each agent on a consent screen that lists the scopes it asked for, and can revoke any agent from Settings.
  • Every operation records who acted and why. The user sees this history as agent activity, and it is part of their export.
  • Writes change Candor's records only. Candor cannot move money, trade, pay bills, or change a bank account.

The agent and model are the user's choice

Candor exposes the same operations over every surface and works with the agent the user already has.

  • REST with an OpenAPI contract, a remote MCP server, the candor CLI, and Agent Skills.
  • Setup guides for ChatGPT, Claude, Claude Code, Codex, Gemini CLI, Meta Muse, Grok Bot, OpenClaw, and Hermes, and other agents that can add a remote MCP server and complete OAuth.
  • The agent package is source-available on GitHub, and the user can export their whole workspace as JSON.

A review, step by step

Each step is recorded in the activity history with the agent's reason.

  1. Open the workspace: the latest review, notes now due, and data that has gone stale.
  2. Read the evidence: the transactions, recurring charges, balances, or holdings an area points at.
  3. Save the outcome: the goal, budget, rule, or note it worked out with the user.
  4. Record what came of it: looked into, with what it found, set aside, or waiting on the person. The dashboard shows it and the next review reads it.
  5. Track it: on later openings, each goal reports its progress, the amount left, and a projected finish date.

REST quickstart

Read the OpenAPI document first. Complete OAuth through the supported Candor setup flow, then call the versioned endpoint you need with a concise reason. POST operations require a stable Idempotency-Key so a retry cannot duplicate a logical write.

GET https://api.candor.money/v1/status
Authorization: Bearer <access-token>
X-Candor-Reason: Check workspace readiness

Versioning and deprecation

Public REST routes are versioned under /v1. Backward-compatible fields may be added within that version. A breaking contract moves to a new version. If a published operation is retired, Candor documents the replacement and timeline and sends the standard Deprecation and Sunset response headers before removal.

Production accounts are real financial workspaces; Candor does not advertise a public sandbox that could be mistaken for one. Use the published schemas and a user-controlled test account for integration development, without real credentials or raw financial data.

For the complete installation decision tree, start at START.md. For implementation questions that do not include private financial data, email support@candor.money.