Project Documentation
·
API Endpoints
·
API Guide
·
Community
·
Blog
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.
- Project status
- Usage
- As an API
- As a Go module
- Learn about Fed services participation
- Getting help
- Supported and tested platforms
- Contributing
- Related projects
- Copyright
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!
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.
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
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
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
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
}
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"
}
]
}
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
| 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 |
| 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 |
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.
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
- 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
| 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. |
- 64-bit Linux (Ubuntu, Debian), macOS, and Windows
Note: 32-bit platforms have known issues and are not supported.
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.
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.
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.
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.
(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.
THIS REPOSITORY IS NOT AFFILIATED WITH THE FEDERAL RESERVE BANKS AND IS NOT AN OFFICIAL SOURCE FOR FEDWIRE AND FEDACH DATA.
Apache License 2.0 - See LICENSE for details.