# BankDataStack — full reference

> Global bank & card data validation APIs — US routing numbers, card BINs, IBANs, and SWIFT/BIC codes.
> Authentication: `Authorization: Bearer YOUR_KEY` header (an `X-API-Key: YOUR_KEY` header also works).
> Base URL: `https://www.bankdatastack.com/api/v1`

## POST /routing/validate

Validates a US bank routing number (ABA number): checks length, the ABA mod-10 checksum, and the assigned bank, then returns the bank's name, address, and ACH/wire eligibility.

Parameters (JSON body):
- `routing_number` (required) — Exactly 9 digits, e.g. "021000021".
- `payment_type` (optional) — "ach" or "wire". Omit to get the first available payment rail.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/validate" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing_number":"021000021","payment_type":"ach"}'
```

MCP equivalent: tools/call with name="validate_routing_number"

## POST /routing/database/lookup

Looks up a US routing number in the local database (19,000+ US banks and credit unions) — richer than validate_routing_number (full address, phone, revision date). Pass refresh=true to force a fresh upstream lookup.

Parameters (JSON body):
- `routing_number` (required) — Exactly 9 digits, e.g. "021000021".
- `refresh` (optional) — Boolean. Force a fresh upstream lookup instead of using the cached record. Defaults to false.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/database/lookup" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing_number":"021000021"}'
```

MCP equivalent: tools/call with name="lookup_routing_number_db"

## POST /routing/database/search

Advanced multi-filter search across the local routing number database — bank, city, state, and/or zip. At least one filter is required. Paginated, max 10 results/page.

Parameters (JSON body):
- `bank` (optional) — Bank name, partial match, at least 2 characters.
- `city` (optional) — City name, at least 2 characters.
- `state` (optional) — 2-letter US state code or full name, at least 2 characters.
- `zip` (optional) — ZIP code, at least 5 characters.
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/database/search" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"NY","limit":5}'
```

MCP equivalent: tools/call with name="search_routing_numbers"

## POST /routing/database/bank

Search the local routing number database by bank name (partial match). Paginated, max 10 results/page.

Parameters (JSON body):
- `bank` (required) — Bank name, partial match, at least 2 characters, e.g. "Chase".
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/database/bank" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bank":"Chase"}'
```

MCP equivalent: tools/call with name="search_banks_by_name"

## POST /routing/database/state

List banks and credit unions registered in a US state, from the local routing number database. Paginated, max 10 results/page.

Parameters (JSON body):
- `state` (required) — 2-letter US state code or full state name, e.g. "NY".
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/database/state" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"NY"}'
```

MCP equivalent: tools/call with name="search_banks_by_state"

## POST /routing/database/city

List banks and credit unions registered in a city, from the local routing number database. Optionally narrow by state. Paginated, max 10 results/page.

Parameters (JSON body):
- `city` (required) — City name, at least 2 characters.
- `state` (optional) — Optional 2-letter US state code to disambiguate same-named cities.
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/database/city" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"Springfield","state":"IL"}'
```

MCP equivalent: tools/call with name="search_banks_by_city"

## POST /routing/database/zip

List banks and credit unions registered in a ZIP code, from the local routing number database. Paginated, max 10 results/page.

Parameters (JSON body):
- `zip` (required) — ZIP code, at least 5 characters.
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/routing/database/zip" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zip":"10001"}'
```

MCP equivalent: tools/call with name="search_banks_by_zip"

## POST /bin/lookup

Looks up a card Bank Identification Number (the first 6-8 digits of a card number) and returns the issuing bank, card brand (Visa/Mastercard/Amex/...), card type and level, and country.

Parameters (JSON body):
- `bin` (required) — 6-8 digit Bank Identification Number, e.g. "411111".

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/bin/lookup" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bin":"411111"}'
```

MCP equivalent: tools/call with name="lookup_bin"

## POST /iban/validate

Validates an International Bank Account Number: checks the country participates in IBAN, the length matches that country's format, and the MOD-97 checksum, then returns the country code, check digits, and BBAN.

Parameters (JSON body):
- `iban` (required) — 15-34 characters, e.g. "DE89370400440532013000". Spaces are stripped automatically.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/iban/validate" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iban":"DE89370400440532013000"}'
```

MCP equivalent: tools/call with name="validate_iban"

## POST /swift/lookup

Looks up a SWIFT/BIC code in the local registry and returns the associated bank, branch, city, address, and country.

Parameters (JSON body):
- `swift` (required) — 8-11 alphanumeric characters, e.g. "DEUTDEFF" or "CHASUS33XXX".

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/swift/lookup" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"swift":"DEUTDEFF"}'
```

MCP equivalent: tools/call with name="lookup_swift"

## POST /swift/search

Advanced multi-filter search across the SWIFT/BIC registry — bank, city, country, and/or 2-letter country code. At least one filter is required. Paginated, max 10 results/page.

Parameters (JSON body):
- `bank` (optional) — Bank name, partial match, at least 2 characters.
- `city` (optional) — City name, at least 2 characters.
- `country` (optional) — Country name, at least 2 characters.
- `country_code` (optional) — 2-letter ISO country code, e.g. "US" or "GB".
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/swift/search" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"DE","limit":5}'
```

MCP equivalent: tools/call with name="search_swift_codes"

## POST /swift/bank

List all SWIFT/BIC codes for a bank name (partial match) — a bank can have multiple codes across branches. Paginated, max 10 results/page.

Parameters (JSON body):
- `bank` (required) — Bank name, partial match, at least 2 characters, e.g. "Deutsche Bank".
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/swift/bank" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bank":"Deutsche Bank"}'
```

MCP equivalent: tools/call with name="search_swift_by_bank"

## POST /swift/country

List all SWIFT/BIC codes registered in a country. Paginated, max 10 results/page.

Parameters (JSON body):
- `country_code` (required) — 2-letter ISO country code, e.g. "DE" or "US".
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/swift/country" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"DE"}'
```

MCP equivalent: tools/call with name="search_swift_by_country"

## POST /swift/city

List all SWIFT/BIC codes registered in a city. Optionally narrow by country code. Paginated, max 10 results/page.

Parameters (JSON body):
- `city` (required) — City name, at least 2 characters.
- `country_code` (optional) — Optional 2-letter ISO country code to disambiguate same-named cities.
- `limit` (optional) — Results per page, 1-10. Defaults to 10.
- `page` (optional) — Page number, starting at 1. Defaults to 1.

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/swift/city" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"Frankfurt"}'
```

MCP equivalent: tools/call with name="search_swift_by_city"

## POST /bic/validate

Validates a BIC (same format as SWIFT) against the local registry and returns a detailed breakdown (bank code, country code, location code, branch code) alongside the bank, branch, and address.

Parameters (JSON body):
- `bic` (required) — 8-11 alphanumeric characters, e.g. "CHASUS33" or "DEUTDEFF".

Example:
```
curl -X POST "https://www.bankdatastack.com/api/v1/bic/validate" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bic":"DEUTDEFF"}'
```

MCP equivalent: tools/call with name="validate_bic"

## register (MCP-only tool — no REST equivalent, no API key required to call it)

Issues a free, low-quota sandbox credential with no human signup and no credit card, by calling `POST /oauth/register` (RFC 7591-lite Dynamic Client Registration) then `POST /oauth/token` (RFC 6749 §4.4 Client Credentials Grant) on the agent's behalf.

Parameters:
- `client_name` (optional) — a label for this credential, e.g. "my-agent". Defaults to "mcp-agent".
- `contact_email` (optional) — abuse contact only, not verified. Defaults to a placeholder.

Returns an `access_token` (use as `Authorization: Bearer <access_token>` on every subsequent tool call), its `expires_in` seconds, and the account quota (200 requests/month, 5 requests/minute, expires in 7 days). This is a sandbox credential for evaluation — for production-scale access, use human signup at https://www.bankdatastack.com/register instead (paid plans, 7-day free trial).

MCP equivalent: tools/call with name="register"