Retrieve full details for the single bank branch identified by an IFSC code.

Use this whenever the user supplies an IFSC. It is the only tool that confirms a branch actually exists, and the only source of the branch's address, MICR, SWIFT/bic code, contact number and per-branch settlement-rail support (RTGS, NEFT, IMPS, UPI).

Returns ok: true with: ifsc, bank, bank_code, branch, centre, address, city, district, state, iso3166, micr, contact, swift, and supports (booleans for imps/neft/rtgs/upi/swift).

Failure codes: INVALID_INPUT (not 11 chars, or not 4 letters + '0' + 6 alphanumerics), NOT_FOUND (well-formed but no such branch), UPSTREAM_TIMEOUT / UPSTREAM_UNAVAILABLE / UPSTREAM_ERROR (service trouble).

Args: ifsc: The 11-character IFSC to resolve, e.g. "SBIN0000001".

Returns: The branch record, or a structured error payload with ok: false.

Example: Ask "what is the MICR of HDFC0000001?" -> call ifsc_lookup("HDFC0000001").

Check whether a string is structurally a valid IFSC, without any network call.

Applies the RBI/NEFC layout rules offline: exactly 11 characters, 4 leading letters for the bank code, a literal '0' as the 5th character, and 6 trailing alphanumeric branch characters.

Choose this over ifsc_lookup when you want to reject junk before spending a request, or to explain why a user-entered code is wrong. It does NOT confirm the branch exists - only ifsc_lookup does that.

Returns ok: true with: input, normalized, is_valid, bank_code, branch_code, reason and message. reason is a stable code: VALID, EMPTY, WRONG_LENGTH, INVALID_CHARACTERS, BAD_BANK_CODE, MISSING_BANK_SUBLET or BAD_BRANCH_CODE.

Args: ifsc: The candidate string to validate.

Returns: A validation report, always with ok: true - an invalid IFSC is a successful report, not an error.

Example: Ask "is HFDCC00001 a valid IFSC?" -> call ifsc_validate("HFDCC00001") and read reason == "MISSING_BANK_SUBLET".

Find bank branches when you have a bank, city, state or branch name but no IFSC.

Filters are ANDed. At least one of bank_code, city, state or branch is required - an unfiltered search is rejected with INVALID_INPUT because the dataset has ~170k rows and no endpoint supports listing all of them.

Returns ok: true with: branches (each row shaped like an ifsc_lookup result), count (total matches upstream), has_next (true when more pages exist), and the echoed query.

Prefer this over bank_directory when the user wants a branch; use bank_directory when they want a bank.

Args: bank_code: 4-letter bank code filter. city: City name filter. state: ISO 3166-2 state code filter, e.g. "IN-MH". branch: Exact branch-name filter. limit: Page size, 1-100 (default 10). offset: Row offset, for pagination.

Returns: Matching branches with pagination metadata, or a structured error payload.

Example: Ask "which Kotak branches are in Gurgaon?" -> call search_branches(bank_code="KKBK", city="GURGAON", limit=5).

Discover the exact district and branch-name spellings that search_branches matches on.

The branch search API matches city/district and branch verbatim, so a near-miss returns zero rows. This tool walks the same hierarchy the API uses, one level per call, and returns the accepted values at that level: bank_code alone -> states; add state -> districts; add district -> branches.

Returns ok: true with level ('states'|'districts'|'branches'), the values at that level, total found, truncated, and the echoed query.

Call this when a search returned nothing and you need to check spelling - it is cheaper than guessing several more search calls.

Args: bank_code: 4-letter bank code; required. state: ISO 3166-2 code to descend to districts, e.g. "IN-MH". district: District name to descend to branches, e.g. "MUMBAI". limit: Cap on returned values, 1-200 (default 200).

Returns: The place names valid at the requested level, or a structured error payload.

Example: Ask "which states does Kotak serve?" -> call branch_places(bank_code="KKBK").

Look up the official 4-letter bank code for a bank, or list banks by name.

Every IFSC begins with a 4-letter bank code, and this is the tool that maps "HDFC Bank" -> "HDFC". Use it before ifsc_lookup or search_branches when the user gave a bank name rather than a code.

Returns ok: true with: banks (list of {"code", "name"}), count (total matches) and source (the upstream dataset URL).

Data comes from the published razorpay/ifsc dataset and is cached, so repeated calls are cheap. This returns banks, not branches - use search_branches or ifsc_lookup for a specific branch.

Args: query: Substring filter over code and name; omit for the full list. limit: Max rows, 1-500 (default 50, or 500 with no query).

Returns: Matching bank codes and names, or a structured error payload.

Example: Ask "what is the code for Kotak Mahindra?" -> call bank_directory(query="kotak") and read banks[0]["code"].

Get bank-level facts for a 4-letter bank code: its type, MICR/IIN, and payment-rail support.

Distinguishes bank classes that share an IFSC prefix pattern - private / public / foreign / small finance / payments / co-operative - and reports whether the bank as a whole supports UPI, ACH credit/debit, NACH debit and APBS.

Choose this over bank_directory when you need capabilities or bank type rather than the name; choose bank_directory when you need to go from a bank name to its code.

Returns ok: true with: bank_code, name, bank_type, micr, iin, capability_ifsc, and capabilities (upi, ach_credit, ach_debit, nach_debit, apbs).

Args: bank_code: The 4-letter bank code, e.g. "KKBK".

Returns: Bank metadata, or a structured error payload (INVALID_INPUT for a malformed code, NOT_FOUND for a code absent from the dataset).

Example: Ask "is HDFC a private bank and does it support UPI?" -> call bank_metadata(bank_code="HDFC").