Worlds / Payments and billing

Plaid API

A local Plaid with Items, linked accounts, balances and a transaction feed with pending and posted entries. Test the agent that syncs transactions, checks balances and handles broken bank links.

Base path: /
Auth: client_id and secret in the request body, the world key
Endpoints: 13
Status: Active today

This reference previews the surface the Plaid world serves in the closed beta. Paths mirror the public Plaid API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_PLAID_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever Plaid expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · plaid

import { Configuration, PlaidApi } from "plaid";

const client = new PlaidApi(new Configuration({
  basePath: process.env.WORLDS_PLAID_URL,
  baseOptions: { headers: {
    "PLAID-CLIENT-ID": "client",
    "PLAID-SECRET": process.env.WORLDS_API_KEY,
  } },
}));

const { data } = await client.accountsGet({ access_token: "access-sandbox-1" });

API reference

13 of 13

Link tokens

Start and finish a bank connection.

POST/link/token/createCreate a link token
POST/item/public_token/exchangeExchange a public token for an access token
POST/sandbox/public_token/createCreate a sandbox public token

Fields · 4

`link_token`	string	Token for the Link flow
`expiration`	string	Token expiry
`public_token`	string	Token to exchange after Link
`access_token`	string	Long-lived item token

Accounts

Bank accounts on a linked item.

POST/accounts/getList accounts for an item
POST/accounts/balance/getGet real-time balances
POST/auth/getGet account and routing numbers
POST/identity/getGet account owner identity

Fields · 5

`account_id`	string	Account id
`name`	string	Account name
`type`	string	depository, credit, loan or investment
`balances`	object	Available and current balance
`mask`	string	Last digits

Transactions

Posted and pending activity on accounts.

POST/transactions/syncSync added, modified and removed transactions
POST/transactions/getGet transactions in a date range
POST/transactions/refreshRequest a refresh

Fields · 6

`transaction_id`	string	Transaction id
`account_id`	string	Account id
`amount`	number	Amount, positive for money out
`date`	string	Posted date
`merchant_name`	string	Cleaned merchant name
`pending`	boolean	Whether it has posted

Items

A connection to one institution.

POST/item/getGet an item
POST/item/removeRemove an item
POST/sandbox/item/reset_loginForce a login required state

Fields · 4

`item_id`	string	Item id
`institution_id`	string	Institution id
`error`	object	Login required or other error
`available_products`	array	Products not yet enabled

Test workflow

Prepare. Select the Plaid setup for your workflow and review its starting records, including link tokens, accounts, transactions.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Stored cursor advanced for every healthy Item
No transaction_id stored twice
Removed pending Uber charge deleted from the ledger
3 Items flagged for update mode, none removed
Payout check used balances.available

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Plaid
version: 2
connector: plaid
seed: plaid-starter
mode: isolated
policy: >
  Bring every Item's transactions up to date. Drop pending entries that were
  removed and do not double count ones that posted. Flag Items that need a
  login instead of deleting them.
tasks:
  - id: sync-transactions-with-the-cursor-and-handle-removals
    prompt: Sync transactions with the cursor and handle removals
  - id: check-available-balance-before-a-payout
    prompt: Check available balance before a payout
  - id: flag-items-that-need-the-user-to-log-in-again
    prompt: Flag Items that need the user to log in again
expected:
  - Stored cursor advanced for every healthy Item
  - No transaction_id stored twice
  - Removed pending Uber charge deleted from the ledger
  - "3 Items flagged for update mode, none removed"
  - Payout check used balances.available
scenarios:
  - login-required
  - not-ready
  - institution-down

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`login-required`	Calls return ITEM_LOGIN_REQUIRED for one Item
`not-ready`	transactions sync returns PRODUCT_NOT_READY on a new Item
`institution-down`	Balance calls return INSTITUTION_DOWN
`rate-limited`	Balance refresh returns RATE_LIMIT_EXCEEDED
`webhook`	SYNC_UPDATES_AVAILABLE arrives while a sync is running

Starting data

Start each run from the same records and relationships. The overview below describes the Plaid starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
items	40 across 12 institutions, 3 in ITEM_LOGIN_REQUIRED
accounts	95 checking, savings and credit
transactions	6,000 with 120 pending
auth	Routing and account numbers for 30 checking accounts

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Link tokens records

Link tokens

Start and finish a bank connection.

Field	Type	Meaning / relationship
`link_token`	string	Token for the Link flow
`expiration`	string	Token expiry
`public_token`	string	Token to exchange after Link
`access_token`	string	Long-lived item token

json · illustrative record shape

{
  "link_token": "<Token for the Link flow>",
  "expiration": "<Token expiry>",
  "public_token": "<Token to exchange after Link>",
  "access_token": "<Long-lived item token>"
}

See link tokens operations

Accounts records

Accounts

Bank accounts on a linked item.

Field	Type	Meaning / relationship
`account_id`	string	Account id
`name`	string	Account name
`type`	string	depository, credit, loan or investment
`balances`	object	Available and current balance
`mask`	string	Last digits

json · illustrative record shape

{
  "account_id": "<Account id>",
  "name": "<Account name>",
  "type": "<depository, credit, loan or investment>",
  "balances": {},
  "mask": "<Last digits>"
}

See accounts operations

Transactions records

Transactions

Posted and pending activity on accounts.

Field	Type	Meaning / relationship
`transaction_id`	string	Transaction id
`account_id`	string	Account id
`amount`	number	Amount, positive for money out
`date`	string	Posted date
`merchant_name`	string	Cleaned merchant name
`pending`	boolean	Whether it has posted

json · illustrative record shape

{
  "transaction_id": "<Transaction id>",
  "account_id": "<Account id>",
  "amount": 1,
  "date": "<Posted date>",
  "merchant_name": "<Cleaned merchant name>",
  "pending": false
}

See transactions operations

Items records

Items

A connection to one institution.

Field	Type	Meaning / relationship
`item_id`	string	Item id
`institution_id`	string	Institution id
`error`	object	Login required or other error
`available_products`	array	Products not yet enabled

json · illustrative record shape

{
  "item_id": "<Item id>",
  "institution_id": "<Institution id>",
  "error": {},
  "available_products": []
}

See items operations

See the Plaid world in the catalog