Skip to content
← Public packages

@kody/plaid

Read Plaid identity, items, accounts, balances, and transactions with sandbox-friendly secret-backed helpers.

FollowFork

Files

README.md

102 lines · 4.7 KB · Markdown

@kody/plaid

Intent

Reusable Plaid helpers so Kody agents can read identity, Items, accounts, balances, and transactions on the caller's Plaid app — not a shared platform connection. Auth is a saved client id plus secret. Reads are free-form and sandbox-first. Link-token creation and other mutations default to a dry-run preview and need confirm: true to run live.

This listing is meant to be forked. After you fork, save your own plaidClientId / plaidSecret and call the helpers in your account. Never ask for or store a bank username or password in chat. Plaid Link (or the Sandbox public-token helper) is how Items are created.

Share this package as https://kody.codes/@kody/plaid

What it does

  • Read Items, accounts, balances, identity, and transactions
  • Browse / search institutions
  • Create Link tokens and Sandbox public tokens (dry-run by default)
  • Exchange public tokens and manage Item webhooks with explicit confirm

Prerequisites / setup

Client id + secret (secret-backed). There is no built-in Plaid OAuth integration and no bank-login flow in this package. Do not open /connect/oauth for Plaid. Do not collect institution credentials in chat.

SecretPurpose
plaidClientIdDashboard client id (PLAID_CLIENT_ID)
plaidSecretDashboard secret (PLAID_SECRET) — sandbox or production key
plaidAccessTokenOptional Item access_token after Link or sandbox exchange
  1. Create keys at dashboard.plaid.com/developers/keys. Prefer sandbox keys first. Never paste the secret or a bank password into chat.
  2. Save the client id:

https://kody.codes/account/secrets/new?name=plaidClientId&description=Plaid%20API%20client%20id%20from%20dashboard.plaid.com%2Fdevelopers%2Fkeys%20(PLAID_CLIENT_ID)&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user

  1. Save the secret:

https://kody.codes/account/secrets/new?name=plaidSecret&description=Plaid%20API%20secret%20from%20dashboard.plaid.com%2Fdevelopers%2Fkeys%20(PLAID_SECRET)&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user

  1. In the account secrets UI, approve hosts sandbox.plaid.com and production.plaid.com on both secrets. Saving a secret does not approve hosts by itself.
  2. Optional Item access token after Link or a confirmed sandbox exchange (this is not a bank password):

https://kody.codes/account/secrets/new?name=plaidAccessToken&description=Plaid%20Item%20access_token%20from%20Link%20or%20sandbox%20public-token%20exchange.%20Not%20a%20bank%20password.&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user

  1. Agents: see AGENTS.md for import paths and smoke checks.

Defaults to the Sandbox API (sandbox.plaid.com). Pass environment: "production" per call to use production.plaid.com. Items cannot move between environments.

Additional accounts

Pass account: "work" to use plaidClientId-work / plaidSecret-work / plaidAccessToken-work, or pass clientIdSecret / secretSecret / accessTokenSecret explicitly.

https://kody.codes/account/secrets/new?name=plaidClientId-work&description=Plaid%20API%20client%20id%20for%20the%20work%20account&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user

https://kody.codes/account/secrets/new?name=plaidSecret-work&description=Plaid%20API%20secret%20for%20the%20work%20account&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user

Bank login policy

Agents must never request, accept, or store a bank username or password. Plaid Link collects those credentials in Plaid's own UI. This package only creates a link_token (dry-run by default) or, in Sandbox, a public token via /sandbox/public_token/create without taking institution credentials.

If Plaid returns ITEM_LOGIN_REQUIRED, create a Link token in update mode and have the owner complete Link again. Do not ask them to type their bank password here.

Done when

  • plaidClientId and plaidSecret are saved; Plaid hosts and package secret access are approved
  • Smoke test returns ok: true (live institutions sample when credentials exist — no Items created, no bank login)
  • Mutations default to dry-run and refuse live calls unless confirm: true

Branding

community-icon.svg is Plaid's official mark from the plaid.com header (same path as Wikimedia File:Plaid logo.svg), on Plaid black #111111. Plaid® is a trademark of Plaid Inc. This package is not affiliated with or endorsed by Plaid.

Docs