Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Plaid Sandbox

Scalekit connector
Open markdown

The Plaid Sandbox connector lets your AI agent act in each user's Plaid Sandbox account. Each user connects their own Plaid Sandbox API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 32 tools.

Tools
32
What they doRead · write · destructive
17 · 12 · 317 read12 write3 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Plaid Sandbox connection

    In AgentKit > Connections, create a Plaid Sandbox connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Plaid Sandbox connections use your Plaid client ID and Sandbox secret, and call Plaid’s Sandbox environment (sandbox.plaid.com) with test banks and test data. When you’re ready for real bank data, use the Plaid connector with your Production secret.

    1. Copy your Plaid keys

      In the Plaid Dashboard, open Developers > Keys and copy your client ID and your Sandbox secret. The client ID is the same in every Plaid environment; the secret is not.

    2. Create the connection

      In the Scalekit dashboard, go to AgentKit > Connections > Create Connection, find Plaid Sandbox and click Create. The connection name is the connection_name your code passes.

    3. Add a connected account

      To test, open the connection, click the Connected Accounts tab > Add Account, enter the user’s identifier, such as user_123, and fill in Client ID and Sandbox Secret.

      In production, each user opens the authorization link and enters the same fields there.

    4. Create a test Item and get its access token

      Most tools take an Item’s access_token as input. An Item is one end user’s login at a bank. In Sandbox, create one without Plaid Link:

      1. Call plaidsandbox_sandbox_public_token_create with institution_id set to ins_109508 (First Platypus Bank, a test bank) and the products you want to test in initial_products, such as ["transactions"].
      2. Pass the returned public_token to plaidsandbox_item_public_token_exchange. It returns the Item’s access_token and item_id.
      3. Pass the access_token on later tool calls, such as plaidsandbox_accounts_get.

      Keep initial_products to the one or two products you’re testing. Creating an Item with many products can take long enough for the call to fail; if it does, retry with fewer products.

    To test the same Link flow your app runs in Production, create a Link token with plaidsandbox_link_token_create, open Plaid Link with it and sign in with Plaid’s test credentials user_good / pass_good.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'plaidsandbox'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Plaid Sandbox:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'plaidsandbox_accounts_balance_get',
      toolInput: { access_token: 'YOUR_ACCESS_TOKEN' },
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Plaid Sandbox credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • plaidsandbox_accounts_balance_getGet real-time balances for an Item's accounts by fetching fresh data from the institution.Read-only

    Get Real-Time Balances

    Get real-time balances for an Item's accounts by fetching fresh data from the institution. Returns accounts with balances (available, current, limit, iso_currency_code, last_updated_datetime) and item. Use plaidsandbox_accounts_balance_get before moving money or whenever balances must be current. Each call is billed and usually takes under 10 seconds, sometimes 30 or more. Use plaidsandbox_accounts_get for free cached balances.

    Inputs

    access_tokenstringrequired
    The Item's access_token, returned by plaidsandbox_item_public_token_exchange after the end user links an account with Plaid Link. It starts with access-sandbox-. Example: access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6.
    account_idsarray
    Limit the accounts returned to these account_ids, from plaidsandbox_accounts_get. Leave empty for all of the Item's accounts. Plaid returns an error if an id does not belong to the Item. Example: ["BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"].
    min_last_updated_datetimestring
    Oldest acceptable balance time, ISO 8601 (YYYY-MM-DDTHH:mm:ssZ). Only needed for institutions that do not return real-time balances (for example Capital One); Plaid returns an error if its balance is older. Example: 2026-10-20T00:00:00Z.
  • plaidsandbox_accounts_getList the active accounts on an Item, with balances cached from Plaid's last update.Read-only

    Get Accounts

    List the active accounts on an Item, with balances cached from Plaid's last update. Returns accounts (account_id, name, official_name, mask, type, subtype, and balances with available, current, limit and iso_currency_code) and item. Use plaidsandbox_accounts_get for account ids, names and types; it is free. Use plaidsandbox_accounts_balance_get when balances must be real-time.

    Inputs

    access_tokenstringrequired
    The Item's access_token, returned by plaidsandbox_item_public_token_exchange after the end user links an account with Plaid Link. It starts with access-sandbox-. Example: access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6.
    account_idsarray
    Limit the accounts returned to these account_ids, from plaidsandbox_accounts_get. Leave empty for all of the Item's accounts. Plaid returns an error if an id does not belong to the Item. Example: ["BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"].
  • plaidsandbox_auth_getGet the account and routing numbers of an Item's checking, savings and cash management accounts.Read-only

    Get Auth (Account and Routing Numbers)

    Get the account and routing numbers of an Item's checking, savings and cash management accounts. Returns numbers (ach with account and routing numbers for US accounts, eft for Canada, international with IBAN and BIC, bacs for the UK), accounts with balances, and item. Use plaidsandbox_auth_get to set up ACH or other bank transfers. The Item must have the auth product. Use plaidsandbox_accounts_get when you only need account names and masks.

    Inputs

    access_tokenstringrequired
    The Item's access_token, returned by plaidsandbox_item_public_token_exchange after the end user links an account with Plaid Link. It starts with access-sandbox-. Example: access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6.
    account_idsarray
    Limit results to these account_ids, from plaidsandbox_accounts_get. Leave empty for all of the Item's accounts. Plaid returns an error if an id does not belong to the Item. Example: ["BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"].
  • plaidsandbox_identity_getGet the account holder information that the institution has on file for an Item's accounts.Read-only

    Get Identity

    Get the account holder information that the institution has on file for an Item's accounts. Returns accounts, each with owners holding names, emails, phone_numbers and addresses (only names are always present), and item. Use plaidsandbox_identity_get to read who owns an account. Use plaidsandbox_identity_match to score data you already have against the bank's records without reading it.

    Inputs

    access_tokenstringrequired
    The Item's access_token, returned by plaidsandbox_item_public_token_exchange after the end user links an account with Plaid Link. It starts with access-sandbox-. Example: access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6.
    account_idsarray
    Limit results to these account_ids, from plaidsandbox_accounts_get. Leave empty for all of the Item's accounts. Plaid returns an error if an id does not belong to the Item. Example: ["BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"].
  • plaidsandbox_identity_matchScore how well a name, phone number, email address and postal address match the account holder data at the institution.Read-only

    Match Identity

    Score how well a name, phone number, email address and postal address match the account holder data at the institution. Returns accounts, each with legal_name, phone_number, email_address and address match scores from 0 to 100 (plus flags such as is_nickname_match and is_postal_code_match), and item. Use plaidsandbox_identity_match to verify that a user owns an account. Provide at least one of the identity fields. Use plaidsandbox_identity_get to read the bank-held data itself.

    Inputs

    access_tokenstringrequired
    The Item's access_token, returned by plaidsandbox_item_public_token_exchange after the end user links an account with Plaid Link. It starts with access-sandbox-. Example: access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6.
    account_idsarray
    Limit matching to these account_ids, from plaidsandbox_accounts_get. Leave empty for all of the Item's accounts. Plaid returns an error if an id does not belong to the Item. Example: ["BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"].
    addressobject
    The user's address with street, city, region, postal_code and country (ISO-3166-1 alpha-2). Example: {"street": "2992 Cameron Road", "city": "Malakoff", "region": "NY", "postal_code": "14236", "country": "US"}.
    email_addressstring
    The user's email address. Example: accountholder0@example.com.
    legal_namestring
    The user's full legal name. Example: Alberta Bobbeth Charleson.
    phone_numberstring
    The user's phone number in E.164 format, +{country code}{number}. Example: +14157452130.
  • plaidsandbox_institutions_getList the financial institutions Plaid supports in the given countries, page by page.Read-only

    List Institutions

    List the financial institutions Plaid supports in the given countries, page by page. Returns institutions (institution_id, name, products, country_codes, routing_numbers, oauth, and url, logo and primary_color when include_optional_metadata is true) and total. Use plaidsandbox_institutions_get to page through or filter all institutions by product, routing number or OAuth. Use plaidsandbox_institutions_search to find a bank by name and plaidsandbox_institutions_get_by_id when you have its id.

    Inputs

    country_codesarrayrequired
    Countries to include institutions from, as ISO-3166-1 alpha-2 codes. Plaid supports US, CA, GB and several EU countries. Example: ["US"].
    countinteger
    Institutions to return per page, 1 to 500. Defaults to 100 in this tool.default 100
    include_optional_metadataboolean
    Set to true to also return each institution's url, logo (base64 PNG) and primary_color. Defaults to false.
    oauthboolean
    Set to true for only institutions with an OAuth login flow, or false for only those without. Leave empty for both.
    offsetinteger
    Number of institutions to skip, for paging. Defaults to 0. Example: 100.default 0
    productsarray
    Only return institutions that support all of these products. Example: ["transactions", "auth"].
    routing_numbersarray
    Only return institutions that match all of these 9-digit routing numbers. Example: ["011000138"].
  • plaidsandbox_institutions_get_by_idGet one institution's details by its Plaid institution_id, including institutions no longer supported for new connections.Read-only

    Get Institution

    Get one institution's details by its Plaid institution_id, including institutions no longer supported for new connections. Returns institution (institution_id, name, products, country_codes, routing_numbers, oauth, connection_availability, and with the options its url, logo, primary_color and per-product health status). Use plaidsandbox_institutions_get_by_id with the institution_id of an Item from plaidsandbox_item_get. Use plaidsandbox_institutions_search to find an id by name.

    Inputs

    country_codesarrayrequired
    Countries to include the institution from, as ISO-3166-1 alpha-2 codes. Plaid supports US, CA, GB and several EU countries. Example: ["US"].
    institution_idstringrequired
    The Plaid institution_id, case-sensitive. Find it in plaidsandbox_item_get or plaidsandbox_institutions_search. Example: ins_109508.
    include_optional_metadataboolean
    Set to true to also return the institution's url, logo (base64 PNG) and primary_color. Defaults to false.
    include_statusboolean
    Set to true to also return the institution's current health per product (status). Defaults to false.
All 45 in Accounting & Finance