> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twinbay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plaid

> Linked bank logins, Plaid's own tokens and Item errors, and a Transactions Sync stream that changes as time advances

The Plaid API in Sandbox, for agents that link bank accounts, read balances and
ACH numbers, or keep a ledger in step with Transactions Sync. Plaid's own
Sandbox is real but uncooperative: its Items update on their own schedule, a
pending charge posts when it posts, and an `ITEM_LOGIN_REQUIRED` or a
`BALANCE_LIMIT` cannot be summoned for a test. This twin answers with Sandbox's
own envelopes, token shapes and replay rules, and moves when the environment
advances.

**Slug:** `plaid`

## What it models

| Area | Modelled |
| - | - |
| Starting account | One Sandbox application and one Item already linked at First Platypus Bank (`ins_109508`) as `user_good`, with Auth and Transactions: Sandbox's fourteen accounts, its transaction history synced, and two card payments still pending |
| Authentication | `client_id` and `secret` in the `PLAID-CLIENT-ID`/`PLAID-SECRET` headers or the body, with Sandbox's precedence (headers win), its format checks and `INVALID_API_KEYS`; access tokens checked for shape, environment and existence, and `ITEM_NOT_FOUND` once rotated or removed |
| Link and Items | `/link/token/create`, `/sandbox/public_token/create` (skipping Link's browser UI, as Plaid recommends for tests), `/item/public_token/exchange` with Sandbox's replay rule, `/item/get` with its status timestamps, and products initialised on first use |
| Accounts | `/accounts/get` with the cached balance and `/accounts/balance/get` with the live one, account filtering, nullable balance fields and `BALANCE_LIMIT` |
| Auth | `/auth/get` ACH numbers for checking, savings and cash management accounts, and `NO_AUTH_ACCOUNTS` |
| Transactions Sync | `/transactions/sync` cursor pages of `added`, `modified` and `removed`, `count`, replay, the `now` cursor, the account filter, `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION`, `/transactions/refresh` and `/sandbox/transactions/create` |
| Item maintenance | `/item/access_token/invalidate`, `/item/webhook/update`, `/item/remove`, and `/sandbox/item/reset_login` |

Advancing the environment delivers a fresh Item's history, completes a refresh,
posts pending transactions (the pending one is `removed`, the posted one
`added` with `pending_transaction_id`) and repairs an Item waiting on its user
to log back in. Directives — `set_item_error`, `set_rate_limit`,
`set_product_ready`, `queue_transaction_change`, `set_sync_mutation` — create
the states no Sandbox call can.

## Not modelled

Identity, Investments, Liabilities, Assets, Income, Transfer, Signal, Payment
Initiation, processor tokens, Enrich, Consumer Report, Beacon, Monitor,
Identity Verification, institutions search, webhook delivery, Link's browser UI
and any test user or institution other than `user_good` at `ins_109508`.
Merchant enrichment of Sandbox-created transactions comes back null. An
operation Plaid has that the twin has not built answers an explicit `501` with
`error_code: NOT_MODELLED`, never a plausible response; a path Plaid does not
have gets Plaid's own `404 NOT_FOUND`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.