Your guide to the Moov Wire API
The Moov Wire project offers an API with several operations for Fedwire messages, including bidirectional conversion between plaintext and JSON formats. While the project’s primary API documentation contains plenty of technical details and examples, the purpose of this guide is to serve as a launching point for new users. We’ll run through a few basic examples of creating, fetching, deleting, and modifying files.
Background
Fedwire is a real-time gross settlement (RTGS) funds transfer system operated by the U.S. Federal Reserve Banks. It’s typically used by financial institutions and businesses for large-value or time-sensitive transactions. Payments are initiated by a sender and passed through the wire network to a receiver (push payment).
Fedwire transfer files, or “messages”, follow a standard format composed of numerical tags and data elements within them. While some tags like sender information and transfer amount are always mandatory, others are only present for specific transfer types. Our Wire API supports all message types and business function codes defined by the Fed.
Initial setup
The easiest way to get started with the Wire API is to install Docker on your system and run the latest Wire image with docker run -p 8088:8088 -p 9098:9098 moov/wire:latest in your terminal. This step automatically pulls the latest image and runs the API on port 8088 with admin metrics on 9098.
To ensure the service is active, you can ping it with curl localhost:8088/ping. If it’s up and running, you’ll receive an HTTP 200 status with PONG as the response body. Otherwise, you’ll see something like Failed to connect to localhost port 8088: Connection refused.
Listing files
curl localhost:8088/files will access a list of wire messages stored in memory. Opening a browser window and setting the URL to localhost:8088/files lets you view the file list quickly. Assuming you haven’t uploaded any files yet, it will return null.
Each file is stored in JSON format and assigned a unique file ID if not already provided within its contents. Since these files can be pretty significant, I recommend using an in-browser JSON formatting tool or jq to view them.
Creating files
With the /create endpoint, you can create Fedwire messages on the server. You can choose to upload plaintext or JSON representations using this same endpoint. We have many sample files in the test/testdata directory of our project and refer to these examples throughout this article.
Uploading a plaintext representation can be done with:
curl -X POST --data-binary "@fedWireMessage-CustomerTransfer.txt" localhost:8088/files/create
Similarly, you can upload a JSON message with:
curl -X POST -H "content-type: application/json" -d "@fedWireMessage-CustomerTransfer.json" localhost:8088/files/create
If creation is successful in either case, you’ll receive a response with the file’s JSON representation. If not, you’ll get a parsing error, as validation is performed automatically upon submission.
Fetching files
Once a file is on the server, you can fetch its contents by supplying its file ID. Use the cURL -o flag to save the files locally.
To retrieve the JSON representation, use:
curl localhost:8088/files/<YOUR-UNIQUE-FILE-ID>
To retrieve the raw Fedwire message format, use:
curl localhost:8088/files/<YOUR-UNIQUE-FILE-ID>/contents
Deleting files
Deleting files stored in memory is as simple as sending a curl DELETE request. For example:
curl -X DELETE localhost:8088/files/<YOUR-UNIQUE-FILE-ID>
Replacing a Fedwire message
You can replace the Fedwire message associated with an existing file using the /FEDWireMessage endpoint. The new message must be in JSON format and cannot contain a file ID, as it will inherit an existing one specified in the API call. To replace a message, use:
curl -X POST -d "@new-message.json" localhost:8088/files/<YOUR-UNIQUE-FILE-ID>/FEDWireMessage
Summary
We hope this walkthrough helps you get started with Wire and serves as a quick refresher for current users. The API is only a fraction of the entire project, so we encourage you to visit Wire on GitHub too! If you have any questions or suggestions for Wire, please contact the Moov team on Slack (#wire channel) or submit an issue.
