Project Documentation · API Endpoints · API Guide · Community · Blog

moov-io/fed

Moov's mission is to give developers an easy way to create and integrate bank processing into their own software products. Our open source projects are each focused on solving a single responsibility in financial services and designed around performance, scalability, and ease of use.

Fed implements utility services for searching the United States Federal Reserve System such as ABA routing numbers, financial institution name lookup, and Fedwire and FedACH routing information. The HTTP server is available in a Docker image and the Go package github.com/moov-io/fed is available. Moov's primary usage for this project is with ACH origination in our paygate project.

The data and formats in this repository represent a compilation of FedWire and FedACH data from the Federal Reserve Bank Services site. Both the official Fed plaintext and JSON file formats are supported.

Table of contents

• Project status
• Usage
  • As an API
    • Docker (Config)
    • Google Cloud (Config)
    • Data persistence
  • As a Go module
• Learn about Fed services participation
• Getting help
• Supported and tested platforms
• Contributing
• Related projects
• Copyright

Project status

Moov Fed is actively used in multiple production environments. Please star the project if you are interested in its progress. We would appreciate any issues created or pull requests. Thanks!

Usage

The Fed project implements an HTTP server and Go library for searching for FedACH and Fedwire participants.

Note: The data files included in this repository (FedACHdir.md and fpddir.md) are outdated and from 2018. The Fed no longer releases this data publicly and licensing on more recent files prevents us from distributing them. However, the Fed still complies this data and you can retrieve up-to-date files for use in our project, either from LexisNexis or your financial institution.

Moov Fed can read the data files from anywhere on the filesystem. This allows you to mount the files and set FEDACH_DATA_PATH / FEDWIRE_DATA_PATH environmental variables. Both official formats from the Federal Reserve (plaintext and JSON) are supported.

Download files

The Federal Reserve Board (FRB) eServices offers API access to download the files. To download these files, work with your ODFI / banking partner to obtain a download code. Then run Fed with the following environment variables set.

FRB_ROUTING_NUMBER=123456780
FRB_DOWNLOAD_CODE=86cfa5a9-1ab9-4af5-bd89-0f84d546de13

Download files from proxy

Fed can download the files from a proxy or other HTTP resources. The optional URL template is configured as an environment variable. If the URL template is not configured, Fed will download the files directly from FRB eServices by default. This value is considered a template because when preparing the request Fed replaces %s in the path with the requested list name(fedach or fedwire).

FRB_DOWNLOAD_URL_TEMPLATE=https://my.example.com/files/%s?format=json

Docker

We publish a public Docker image moov/fed from Docker Hub or use this repository. No configuration is required to serve on :8086 and metrics at :9096/metrics in Prometheus format. We also have Docker images for OpenShift published as quay.io/moov/fed.

Pull & start the Docker image:

docker pull moov/fed:latest
docker run -p 8086:8086 -p 9096:9096 moov/fed:latest

ACH routing number example

Fed can be used to look up Financial Institutions for Automated Clearing House (ACH) transfers by their routing number (?routingNumber=...):

curl "localhost:8086/fed/ach/search?routingNumber=273976369"

{
  "achParticipants": [
    {
      "routingNumber": "273976369",
      "officeCode": "O",
      "servicingFRBNumber": "071000301",
      "recordTypeCode": "1",
      "revised": "041513",
      "newRoutingNumber": "000000000",
      "customerName": "VERIDIAN CREDIT UNION",
      "achLocation": {
        "address": "1827 ANSBOROUGH",
        "city": "WATERLOO",
        "state": "IA",
        "postalCode": "50702",
        "postalCodeExtension": "0000"
      },
      "phoneNumber": "3192878332",
      "statusCode": "1",
      "viewCode": "1"
    }
  ],
  "wireParticipants": null
}

Wire routing number example

Fed can be used to look up Financial Institutions for Fedwire messages by their routing number (?routingNumber=...):

curl "localhost:8086/fed/wire/search?routingNumber=273976369"

{
  "achParticipants": null,
  "wireParticipants": [
    {
      "routingNumber": "273976369",
      "telegraphicName": "VERIDIAN",
      "customerName": "VERIDIAN CREDIT UNION",
      "wireLocation": {
        "city": "WATERLOO",
        "state": "IA"
      },
      "fundsTransferStatus": "Y",
      "fundsSettlementOnlyStatus": " ",
      "bookEntrySecuritiesTransferStatus": "N",
      "date": "20141107"
    }
  ]
}

Google Cloud Run

To get started in a hosted environment you can deploy this project to the Google Cloud Platform.

From your Google Cloud dashboard create a new project and call it:

moov-fed-demo

Enable the Container Registry API for your project and associate a billing account if needed. Then, open the Cloud Shell terminal and run the following Docker commands, substituting your unique project ID:

docker pull moov/fed
docker tag moov/fed gcr.io/<PROJECT-ID>/fed
docker push gcr.io/<PROJECT-ID>/fed

Deploy the container to Cloud Run:

gcloud run deploy --image gcr.io/<PROJECT-ID>/fed --port 8086

Select your target platform to 1, service name to fed, and region to the one closest to you (enable Google API service if a prompt appears). Upon a successful build you will be given a URL where the API has been deployed:

https://YOUR-FED-APP-URL.a.run.app

Now you can ping the server:

curl https://YOUR-FED-APP-URL.a.run.app/ping

You should get this response:

PONG

Configuration settings

Environmental Variable	Description	Default
FEDACH_DATA_PATH	Filepath to FedACH data file	./data/FedACHdir.txt
FEDWIRE_DATA_PATH	Filepath to Fedwire data file	./data/fpddir.txt
FRB_ROUTING_NUMBER	Federal Reserve Board eServices (ABA) routing number used to download FedACH and FedWire files	Empty
FRB_DOWNLOAD_CODE	Federal Reserve Board eServices (ABA) download code used to download FedACH and FedWire files	Empty
FRB_DOWNLOAD_URL_TEMPLATE	URL Template for downloading files from alternate source	https://frbservices.org/EPaymentsDirectory/directories/%s?format=json
LOG_FORMAT	Format for logging lines to be written as.	Options: json, plain - Default: plain
HTTP_BIND_ADDRESS	Address for Fed to bind its HTTP server on. This overrides the command-line flag -http.addr.	Default: :8086
HTTP_ADMIN_BIND_ADDRESS	Address for Fed to bind its admin HTTP server on. This overrides the command-line flag -admin.addr.	Default: :9096
HTTPS_CERT_FILE	Filepath containing a certificate (or intermediate chain) to be served by the HTTP server. Requires all traffic be over secure HTTP.	Empty
HTTPS_KEY_FILE	Filepath of a private key matching the leaf certificate from HTTPS_CERT_FILE.	Empty

Logos

Environmental Variable	Description	Default
CLEARBIT_API_KEY	API key for connecting to Clearbit for logo requests.	Empty
LOGO_CACHE_SIZE	Maximum size for an in-memory cache of logos.	Empty

Data persistence

By design, Fed does not persist (save) any data about the search queries created. The only storage occurs in memory of the process and upon restart Fed will have no files or data saved. Also, no in-memory encryption of the data is performed.

Go library

This project uses Go Modules and Go v1.18 or newer. See Golang's install instructions for help setting up Go. You can download the source code and we offer tagged and released versions as well. We highly recommend you use a tagged release for production.

$ git@github.com:moov-io/fed.git

# Pull down into the Go Module cache
$ go get -u github.com/moov-io/fed

$ go doc github.com/moov-io/fed ACHDictionary

Learn about Fed services participation

• Intro to Fedwire
• Intro to FedACH
• U.S. Department of the Treasury FAQ
• State and Territory Abbreviations
• Fedwire Directory File Format
• FedACH Directory File Format

Getting help

channel	info
Project Documentation	Our project documentation available online.
Twitter @moov	You can follow Moov.io's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories.
GitHub Issue	If you are able to reproduce a problem please open a GitHub Issue under the specific project that caused the error.
moov-io slack	Join our slack channel to have an interactive discussion about the development of the project.

Supported and tested platforms

• 64-bit Linux (Ubuntu, Debian), macOS, and Windows

Note: 32-bit platforms have known issues and are not supported.

Contributing

Yes please! Please review our Contributing guide and Code of Conduct to get started!

This project uses Go Modules and Go v1.18 or newer. See Golang's install instructions for help setting up Go. You can download the source code and we offer tagged and released versions as well. We highly recommend you use a tagged release for production.

Releasing

To make a release of fed simply open a pull request with CHANGELOG.md and version.go updated with the next version number and details. You'll also need to push the tag (i.e. git push origin v1.0.0) to origin in order for CI to make the release.

Testing

We maintain a comprehensive suite of unit tests and recommend table-driven testing when a particular function warrants several very similar test cases. To run all test files in the current directory, use go test. Current overall coverage can be found on Codecov.

Related projects

As part of Moov's initiative to offer open source fintech infrastructure, we have a large collection of active projects you may find useful:

• Moov Watchman offers search functions over numerous trade sanction lists from the United States and European Union.

• Moov Image Cash Letter implements Image Cash Letter (ICL) files used for Check21, X.9 or check truncation files for exchange and remote deposit in the U.S.

• Moov Wire implements an interface to write files for the Fedwire Funds Service, a real-time gross settlement funds transfer system operated by the United States Federal Reserve Banks.

• Moov ACH provides ACH file generation and parsing, supporting all Standard Entry Codes for the primary method of money movement throughout the United States.

• Moov Metro 2 provides a way to easily read, create, and validate Metro 2 format, which is used for consumer credit history reporting by the United States credit bureaus.

Copyright and terms of use

(c) Federal Reserve Banks

By accessing the data in this repository you agree to the Federal Reserve Banks' Terms of Use and the E-Payments Routing Directory Terms of Use Agreement.

Disclaimer

THIS REPOSITORY IS NOT AFFILIATED WITH THE FEDERAL RESERVE BANKS AND IS NOT AN OFFICIAL SOURCE FOR FEDWIRE AND FEDACH DATA.

License

Apache License 2.0 - See LICENSE for details.