Web API Specifications for the
TRACE Treasury Securities
File Downloads
Version 4.1
August 20, 2024
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
i
Table of Contents
Revision History ............................................................................................................................................ 1
Introduction .................................................................................................................................................. 2
Access to the Download API ......................................................................................................................... 2
Acquiring the Refresh Token in TRAQS ......................................................................................................... 4
Requesting An Access Token......................................................................................................................... 7
Requesting a File with an Access Token ....................................................................................................... 8
Protocol ......................................................................................................................................................... 9
File Availability – All Times are Approximate ................................................................................................ 9
URL Parameters .......................................................................................................................................... 10
File Definitions - All Files are Pipe Delimited .......................................................................................... 11
TRACE for Treasury Securities Security Master Files .......................................................................... 11
TRACE for Treasury Securities Daily List (for Securities) ..................................................................... 12
TRACE for Treasury Participant List .................................................................................................... 13
TRACE for Treasury Participant Daily List ............................................................................................ 13
TRACE for Treasury Securities US Agreements File ............................................................................ 14
Example Requests ................................................................................................................................... 15
Example 1 - Get the current TRACE for Treasury Participant List ....................................................... 15
Example 2 - Get the TRACE for Treasury Participant Daily List for 7/10/2017 ................................... 15
Example 3 - Get today’s TRACE for Treasury Participant Daily List (no day provided) ....................... 15
Example 4 - Get changes to the TRACE for Treasury Participant Daily List since the last download (no
day provided) ...................................................................................................................................... 15
Example 5 - Get the current Treasury Security Master file................................................................ 15
Example 6 - Get today’s TS Daily List (no day provided) ..................................................................... 15
Sample Results ........................................................................................................................................ 16
TRACE for Treasury Securities Security Master File Illustrating the Header and Footer .................... 16
TRACE for Treasury Securities Daily List File Illustrating the Header and Footer ............................... 16
TRACE for Treasury Participant Daily List File Illustrating the Header and Footer ............................. 17
TRACE for Treasury Participant List File Illustrating the Header and Footer ...................................... 17
Appendices .................................................................................................................................................. 18
Appendix 1 – Treasury Securities Coupon Type Codes and Descriptions ............................................... 18
Appendix 2 - Daily List Update Reason Codes and Descriptions ............................................................ 18
Programmatic Access Example(curl) ........................................................................................................... 20
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
1
Revision History
Version
Date
Changes Made
Version 1.0
October 17, 2016
• Original version of specification
Version 2.0
April 26, 2017
• Eliminated 144A Indicator from Security Master File; the field is
now a Reserved field.
Version 3.0
June 13, 2017
• Modified Participant List query string, Participant Daily List query
string, and Participant Daily List Delta query string so that only
TRACE for Treasury participants are returned in each query and
not TRACE participants as a whole.
Version 3.1
May 15, 2023
• Updated BSYM_ID definition
Version 4.0
April 29, 2024
• Removed certificate references and added new M2M API
information
• New string URL – starts with apidownload
Version 6.1
August 20, 2024
• Added new Requesting a File with an Access Token section
• Updated username description in Requesting and Access Token
section
• Added an ‘s’ to the http in the Programmatic Access Example
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
2
Introduction
The FINRA TRACE Reporting and Quotation Service is a system developed which consolidates the various fixed
income and equity reporting facilities FINRA currently maintains (e.g., TRACE, ADF, OTC Equity Reporting, etc…)
into a single platform. The secure web interface offers member firms enhanced reporting and data retrieval
functionality.
The Download site for Treasury securities supports clients via a Web Application Programming Interface (API) to
download security master files, and daily lists.
This document pertains specifically to Treasury securities reference data. This document outlines the
parameters and values for each available Treasury securities file. The data in each of these files is current as of
the time of download.
Access to the Download API
Clients who wish to programmatically access the API must request a Refresh Token via the TRAQS Website with
their OKTA profile login. This Refresh Token will be used to obtain an Access Token. This Access Token will use a
“Bearer Token,” which will allow clients to request the API files without having to collect credentials.
The Refresh Token is valid for 6 months. The Access Token expires every hour (3600 seconds). It is the client’s
responsibility to programmatically request a new Access Token when it expires using the Refresh Token.
To access TRAQS, a username, password, and NASDAQ Multi-Factor Authentication (MFA) is required. To
establish a TRAQS username, please consult your Super Account Administrator (SAA) and use the Participant
Data Management (PDM) system.
The data contained in the API files are maintained by FINRA Operations. For questions concerning the data,
PDM, or to access the files, please contact FINRA Operations at (866) 776-0800 option 2 or
FINRAOperations@finra.org. For technical questions or issues accessing the files, please contact FINRA Client
and System Management at FINRA-TSCSM@finra.org.
Data is compiled from multiple sources, including but not limited to Refinitiv, S&P, Moody’s, and Black Knight
Technologies.
Access to the File Domain
Treasury securities file downloads use the NASDAQ Web Security Framework (NWSF) for authentication (proper
client authorization for access to particular files must be in place). In order to access the site and download files,
a user needs to present a valid NWSF account/password and client certificate with access to the application.
The data contained in these files are maintained by FINRA Operations. For questions concerning the data, or to
subscribe to receive these files, please contact FINRA Operations at (866) 776-0800 or
FINRAOperations@finra.org. For technical questions or issues accessing the files, please contact FINRA Product
Management at (866) 899-2107 or FINRAProductManagement@finra.org.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
3
Data is compiled from multiple sources, including but not limited to Refinitiv, S&P, Moody’s, and Black Knight
Technologies.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
4
Acquiring the Refresh Token in TRAQS
1. Log into TRAQS and authenticate using MFA.
2. Click API from the Main Menu.
3. Click Programmatic from the Download Menu (this is where the Refresh Token is obtained).
4. Click Get Token from the API Download Programmatic screen.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
5
5. After requesting the Refresh Token, the system will ask you to Authenticate again. If successful, the user
will be brought back to the API Download Programmatic screen and the Refresh Token information will
be populated under the “Current Token” portion of the screen.
6. Click Copy Token and paste the Refresh Token into your script.
7. Add code to your script to request an Access Token.
8. Upon logging into the API domain from your application, your application will request a new Access
Token from the TRAQS download server.
9. Your application will apply the new Access Token to the download API request call.
10. On success, the requested data will be returned to your application.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
6
11. The user has the ability to Revoke the current Refresh Token at any time, by clicking Revoke Token. This
will inactivate the current Refresh Token and it will move to the Prior Token portion of the screen.
12. If the current Refresh Token is expired, click Get Token which will generate a new Refresh token and the
expired Refresh Token will move to the Prior Token portion of the screen.
Note: Users will be notified via email 15 days prior to Refresh Token expiration. You cannot download
the API files if the Refresh Token or Access Token are expired. Refresh Tokens that expire will need to
be requested manually following step 3 above and updated in your script.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
7
Requesting An Access Token
To programmatically request a new Access Token, clients will send a POST request to
https://apidownload.finratraqs.org/refresh
In the body of the request, you will need to supply values to the following required parameters.
refreshtoken – refresh token request from the TRAQS website
username – the TRAQS username NOT the email address the NWSF username was used to initially
request the legacy API.
This will return the following sample JSON response:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token":
"eyJraWQiOiIwVlRIdEFidXZFOUVzVkNkNGtYS3FIYXU5ZWJqbHRRbENSMXc4MGJPTTgwIiwiYWxnIjoiUlMyNTYifQ.e
yJ2ZXIiOjEsImp0aSI6IkFULklhY3FWeDFSOUs3dmVNWGhFU09iOEhNNHZEaGE1Q1Fma2pEQVlzOXM4R0kub2FyNnFzd2
hxbGR0RzV4cUoweDYiLCJpc3MiOiJodHRwczovL21wcC10ZXN0Lm5hc2RhcS5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQ
iOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNzEyNTkyOTY5LCJleHAiOjE3MTI1OTY1NjksImNpZCI6IjBvYTV3bHA0ZXF4
c05PWlRqMHg3IiwidWlkIjoiMDB1cWwybXltZWhqQ250bzMweDYiLCJzY3AiOlsib2ZmbGluZV9hY2Nlc3MiXSwiYXV0a
F90aW1lIjoxNzExMDc2NDM1LCJzdWIiOiJsdWlzLmJhbGxlbmFAbmFzZGFxLmNvbSIsInFjX3VzZXJuYW1lIjpbImJhbG
xlbmFsIiwibGJhbGxlbmEiLCJsYmFsbGVuYTEiLCJiYWxsZW5hbDEiLCJsdWlzYmFsIiwiYmFsbGx1aXMiLCJsdWJhbGw
iLCJiYWxsbmZzYyJdfQ.FuBh5F0gdLLUxeJbSkfXxpqVDuIjCEi22hn5P9_nexbEJjstAueWYe8T3mVoyGdmJa9-
jdMwsj_OodJeqk0E-4J9tpXZ1roc609K4lk5BM1wQDxlgZp2ToWbbYI-
VQYQ_49cZxFGX_6ih43TrsmQcA_lQoeYRrTzThET5NH_Q5RIQxKmkYiWXQRmXu0mhwjnc74jCjBY8t96tLoy-3OwDCP-
k_Fz7UNqCUIv1MtWqcp3zWgfhPsvswV4eRfj2iSgEwH_A4acpkxTSMWmauXbCeliMfFdnyrQR1sA055-9WH9pJ-
c2MsB4cpNRO9n0tC3SKWD5l6aFTgE1KiLnIvPKQ",
"scope": "offline_access",
"refresh_token": "Zr0_0q3fSmXJXhHNQWs7YBXyt-OFftUMIqywc8VIxHI"
}
The Access Token will be in the JSON response.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
8
Requesting a File with an Access Token
To programmatically request a file, clients will send a request to the specified API URL request – e.g.
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=PARTICIPANT&facility=TR
ACE [apidownload.finratraqs.org] (see URL Parameters and Example Request sections for more information).
The following must be considered when sending the request:
1. All API file requests must be a secure request using https.
2. The API Request must use Authorization Bearer as the authentication type. Therefore, your header in
your request but include “Authorization: Bearer <Access Token>” (see Requesting an Access Token
section).
3. All API files request must be a POST request, and include following the parameters in the body of the
request:
− username=<assigned username> (<assigned username> is the assigned TRAQS username NOT
the email address).
Example request using CURL
curl -s -OJ -X POST
--url
"https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=PARTICIPANT&fac
ility=TRACE [apidownload.finratraqs.org]
--header "Authorization: Bearer
"eyJraWQiOiIwVlRIdEFidXZFOUVzVkNkNGtYS3FIYXU5ZWJqbHRRbENSMXc4MGJPTTgwIiwiYWxnIjoiUlMyNTYifQ.e
yJ2ZXIiOjEsImp0aSI6IkFULklhY3FWeDFSOUs3dmVNWGhFU09iOEhNNHZEaGE1Q1Fma2pEQVlzOXM4R0kub2FyNnFzd2
hxbGR0RzV4cUoweDYiLCJpc3MiOiJodHRwczovL21wcC10ZXN0Lm5hc2RhcS5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQ
iOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNzEyNTkyOTY5LCJleHAiOjE3MTI1OTY1NjksImNpZCI6IjBvYTV3bHA0ZXF4
c05PWlRqMHg3IiwidWlkIjoiMDB1cWwybXltZWhqQ250bzMweDYiLCJzY3AiOlsib2ZmbGluZV9hY2Nlc3MiXSwiYXV0a
F90aW1lIjoxNzExMDc2NDM1LCJzdWIiOiJsdWlzLmJhbGxlbmFAbmFzZGFxLmNvbSIsInFjX3VzZXJuYW1lIjpbImJhbG
xlbmFsIiwibGJhbGxlbmEiLCJsYmFsbGVuYTEiLCJiYWxsZW5hbDEiLCJsdWlzYmFsIiwiYmFsbGx1aXMiLCJsdWJhbGw
iLCJiYWxsbmZzYyJdfQ.FuBh5F0gdLLUxeJbSkfXxpqVDuIjCEi22hn5P9_nexbEJjstAueWYe8T3mVoyGdmJa9-
jdMwsj_OodJeqk0E-4J9tpXZ1roc609K4lk5BM1wQDxlgZp2ToWbbYI-
VQYQ_49cZxFGX_6ih43TrsmQcA_lQoeYRrTzThET5NH_Q5RIQxKmkYiWXQRmXu0mhwjnc74jCjBY8t96tLoy-3OwDCP-
k_Fz7UNqCUIv1MtWqcp3zWgfhPsvswV4eRfj2iSgEwH_A4acpkxTSMWmauXbCeliMfFdnyrQR1sA055-9WH9pJ-
c2MsB4cpNRO9n0tC3SKWD5l6aFTgE1KiLnIvPKQ",
"
--data "username=Finrausr”
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
9
Protocol
FINRA’s API download site provides access to files using standard HTTP Secure (https) protocol. It is a
combination of the Hypertext Transfer protocol and the TLS protocol to provide encrypted communications and
secure identification. The URL https://apidownload.finratraqs.org is the domain where the files reside. In order
to access file reference data users should refer to the query strings detailed in this specification. Examples of
actual download query strings are available in later sections of this specification.
File Availability – All Times are Approximate
File
When Available
Treasury Securities Security Master
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
Treasury Security Daily List
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
Treasury Security Daily List Delta
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
Participant
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
Participant Daily List
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
Participant Daily List Delta
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
US Agreements
Real time starting at 7:00 a.m. ET and throughout the day until
8:00 p.m. ET
NOTE: Users may attempt to access the files on non-business days; however, due to server maintenance which
occurs on weekends and other non-business days it is possible the user will not have immediate success in
access the data during these days.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
10
URL Parameters
Parameter
Parameter Options
action
DOWNLOAD - provide the complete file.
DELTA – provide the changes since the last time the user downloaded the file.
Delta files are supported for Security Daily List and Participant Daily List.
NOT for the Security Master, Participant List, and US Agreements files.
facility
TRACE
file
TSMASTER – Security Master File for Treasury securities
DAILYLISTTS – Security Daily List for Treasury Securities
PARTICIPANTTS – Participant List (current TRACE for Treasury participants with
active authorizations))
PDAILYLISTTS – Participant Daily List (additions/deletions/changes to the
Participant List for TRACE for Treasury)
TSUSA –US Agreements Treasury Securities
day
A date, for example: 1/2/2017. Date is used for Daily List requests.
File
Query Parameters
Treasury Master
action= DOWNLOAD&file=TSMASTER&facility=TRACE
Treasury Security
Daily List
action=DOWNLOAD&file=DAILYLISTTS&facility=TRACE
Treasury Security
Daily List delta
(See note 1)
action=DELTA&file=DAILYLISTTS&facility=TRACE
Treasury Security
Daily List
for a specific day
action=DOWNLOAD&file=DAILYLISTTS&facility=TRACE&day=7/10/2017
TRACE Participant List
action=DOWNLOAD&file=PARTICIPANTTS&facility=TRACE
TRACE Participant
Daily List
action=DOWNLOAD&file=PDAILYLISTTS&facility=TRACE
TRACE Participant
Daily List delta
(see note 1)
action=DELTA&file=PDAILYLISTTS&facility=TRACE
TRACE Participant
Daily List
for a specific day
action=DOWNLOAD&file=PDAILYLISTTS&facility=TRACE&day=07/10/201
7
TRACE Treasury
Security US
Agreements
action=DOWNLOAD&file=TSUSA&facility=TRACE
NOTE 1: All requests are categorized and recorded. When a DELTA request is made, the time of the previous
request is used to determine the items that appear in the DELTA results. The time used for the previous request
is the time of request minus two minutes. This ensures that no updates are missed but it can mean items from a
previous request may appear in the next DELTA request. Systems should be coded with this in mind.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
11
File Definitions - All Files are Pipe Delimited
TRACE for Treasury Securities Security Master Files
Field Name
(Header)
Description
Comments
Maximum
Length
SYM_CD
FINRA assigned Symbol
14
CUSIP_ID
CUSIP
This field will be blank for firms
that do not have a CUSIP license
in place.
9
BSYM_ID
FIGI/Financial Instrument
Global Identifier
12
SUB_PRDCT_TYPE
Sub-Product Type Code
Valid values are:
BILL – Treasury Bill
NOTE – Bonds and Notes
STRP – Strips
TIPS - TIPS
5
ISSUER_NM
Issuer Name
80
SCRTY_DS
Security Description
80
CPN_RT
Coupon Rate
Decimal format
27 (19 after
decimal)
CPN_TYPE_CD
Coupon Type Code
Please see Appendix 1 for a list
of Coupon Type Code /
Descriptions
10
MTRTY_DT
Maturity Date
YYYYMMDD format.
GRADE
Grade
H – High Yield; I – Investment
Grade
1
RESERVED2
Filler
Blank field - reserved for future
use.
RESERVED3
Filler
Blank field - reserved for future
use.
RESERVED4
Filler
Blank field – reserved for future
use.
1
DISSEM
Trade Report Disseminator
Indicator
Y = Indicates trade reports will
be disseminated
N= Indicates trade reports will
not be disseminated
1
Benchmark Start
Date
YYYYMMDD format.
Benchmark End
Date
YYYYMMDD format.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
12
TRACE for Treasury Securities Daily List (for Securities)
Field Name (Header)
Description
Comments
Maximum
Length
DAILY_LIST_DT
Daily List Date
YYYYMMDD format.
DAILY_LIST_TIME
Daily List Time
HH:MM:SS
DAILY_LIST_EVENT_CD
Daily List Event Type
Valid values are:
SA Security Add
SD Security Delete
SC Security Change
2
DAILY_LIST_RSN_CD
Daily List Reason
Reason for the addition,
deletion, or change. This field
may be blank.
Please see Appendix 2 for a list
of Daily List Reason Codes /
Descriptions
5
CMMNT_TX
Event Comment
Free form text field entered by
FINRA Operations. May be
blank.
30
EFCTV_DT
Effective Date
Reflects effective date for the
event affected in the record.
PROD_TYPE
Product Type
Constant “TS”.
SYM_CD
FINRA Symbol
14
CUSIP
This field will be blank for
firms that do not have a CUSIP
license in place.
9
BSYM_ID
FIGI/Financial Instrument
Global Identifier
12
SCRTY_DS
Security Description
250
ISSUER_NM
Issuer Name
255
CPN_RT
Coupon Rate
Decimal format
27 (19 after
decimal)
MTRTY_DT
Maturity Date
YYYYMMDD format.
SUBPROD_TYPE
Sub-Product Type
Valid values are:
BILL – Treasury Bill
NOTE – Bonds and Notes
STRP – Strips
TIPS - TIPS
Note: Changes to Sub- Product
values will be administered by
a Delete then Add Daily List
event.
5
NEW_SYM_CD
New Symbol
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
14
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
13
Field Name (Header)
Description
Comments
Maximum
Length
NEW_CUSIP
New CUSIP
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
9
NEW_BSYM_ID
New FIGI/Financial
Instrument Global
Identifier
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
12
NEW_SCRTY_DS
New Security Description
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
250
NEW_ISSUER_NM
New Issuer
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
255
NEW_CPN_RT
New Coupon Rate
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
27 (19 after
decimal)
NEW_MTRTY_DT
New Maturity Date
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
NEW_SUBPROD_TYPE
New Sub Product Type
Applicable to Change Event
Types only. Will be blank on
Add and Delete Events.
5
TRACE for Treasury Participant List
Field Name (Header)
Description
Comments
Maximum Length
mpid
Market Participant
Identifier
FINRA identifier assigned to the
Treasury participant
6
dba_nm
Firm Name
64
TRACE for Treasury Participant Daily List
Field Name (Header)
Description
Comments
Maximum Length
list_dt
Daily List Date
MMDDYYYY format
effective_dt
Effective Date
MMDDYYYY format
cd_description
Event Type
Valid values are:
Participant Addition
Participant Deletion
Participant Change
old_mpid
Market Participant
Identifier
6
old_dba
Firm Name
64
new_mpid
New Market
Participant Identifier
6
new_dba
New Firm Name
64
rf_cd
Reporting Facility
Value will always be TRACE
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
14
TRACE for Treasury Securities US Agreements File
Field Name (Header)
Description
Comments
Maximum Length
MPID
MPID of the Client
FINRA identifier assigned to the
participant.
6
AGRMT_EFCTV_DT
Effective Date for the
agreement with the
client
Format is YYYYMMDDHHMMSS
14
AGRMT_XPRTN_DT
End date for
agreement with the
client
Format is YYMMDDHHMMSS
12
UNFRM_SRVC_AGRMT
_MP_ID
MPID of client with
who agreement is
based
FINRA identifier assigned to the
participant.
6
US_GIVEUP_DROP_FL
Give Up firm receives
drop copies of
transaction messages
Y or N.
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
15
Example Requests
Example 1 - Get the current TRACE for Treasury Participant List
This request retrieves the current list of TRACE for Treasury authorized Participants:
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=PARTICIPANTTS&facility=T
RACE
Example 2 - Get the TRACE for Treasury Participant Daily List for 7/10/2017
This request retrieves the list of changes to TRACE for Treasury authorized Participants published on 5/1/2017
(note 7/10/2017 is used as an example. Any specific date may be used):
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=PDAILYLISTTS&facility=TR
ACE&day=7/10/2017
Example 3 - Get today’s TRACE for Treasury Participant Daily List (no day provided)
This request retrieves the current day’s cumulative list of changes to TRACE for Treasury authorized Participants:
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=PDAILYLISTTS&facility=TR
ACE
Example 4 - Get changes to the TRACE for Treasury Participant Daily List since the last download
(no day provided)
This request retrieves the latest list of changes to TRACE for Treasury authorized Participants since the last user
download of the Participant List:
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DELTA&file=PDAILYLISTTS&facility=TRACE
Example 5 - Get the current Treasury Security Master file
This request retrieves the current list of all Treasury securities eligible for trade reporting:
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=TSMASTER&facility=TRAC
E
Example 6 - Get today’s TS Daily List (no day provided)
This request retrieves the current day’s cumulative list of changes to all the Treasury Security Master data.
https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOAD&file=DAILYLISTTS&facility=TRA
CE
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
16
Sample Results
TRACE for Treasury Securities Security Master File Illustrating the Header and Footer
TRACE for Treasury Securities Daily List File Illustrating the Header and Footer
SYM_CD|CUSIP_ID|BSYM_ID|SUB_PRDCT_TYPE|ISSUER_NM|SCRTY_DS|CPN_RT|CPN_TYPE_CD|
MTRTY_DT|GRADE|RESERVED2|RESERVED3|RESERVED4|DISSEM|Benchmark Start
Date|Benchmark End Date
TSRYS4493660|912796JE0|BBG00CBVNNC3|BILL|UNITED STATES TREASURY|United States
Treasury Bill|0.0000000000000000000|DSC|20170302|I||||N|20160830|20160906
TSRYS4493662|912796JP5|BBG00CS9FQW4|BILL|UNITED STATES TREASURY|United States
Treasury Bill|0.0000000000000000000|DSC|20170427|I||||N|20170329|20170404
TSRYS4493663|912796JT7|BBG00CXJXJ52|BILL|UNITED STATES TREASURY|United States
Treasury Bill|0.0000000000000000000|DSC|20170525|I||||N|20170426|20170502
TSRYS4493664|912796JX8|BBG00D3CKKX8|BILL|UNITED STATES TREASURY|United States
Treasury Bill|0.0000000000000000000|DSC|20170622|I||||N|20170524|20170530
TSRYS4493667|912796KG3|BBG00DK4LV71|BILL|UNITED STATES TREASURY|United States
Treasury Bill|0.0000000000000000000|DSC|20170209|I||||N|20160809|20160815
…
[snip]
…
TSRYS5587029|912803GT4||STRP|UNITED STATES TREASURY|United States Treasury
Security Stripped Principal
Payment|0.0000000000000000000|STR|20430515|I||||N||
Footer - Count: 00002466, Facility: TRACE, File Created: 20230512151551
DAILY_LIST_DT|DAILY_LIST_TIME|DAILY_LIST_EVENT_CD|DAILY_LIST_RSN_CD|CMMNT_TX|E
FCTV_DT|PROD_TYPE|SYM_CD|CUSIP|BSYM_ID|SCRTY_DS|ISSUER_NM|CPN_RT|MTRTY_DT|SUBP
ROD_TYPE|NEW_SYM_CD|NEW_CUSIP|NEW_BSYM_ID|NEW_SCRTY_DS|NEW_ISSUER_NM|NEW_CPN_R
T|NEW_MTRTY_DT|NEW_SUBPROD_TYPE
20230505|16:27:42|SA||New Security
TS|20230505|TS|TSRYS5584396|912797GS0||United States Treasury Bill|UNITED
STATES TREASURY|0.0000000000000000000|20230914|BILL||||||||
…
[snip]
…
20230505|16:27:42|SA||New Security
TS|20230505|TS|TSRYS5584399|912797FH5||United States Treasury Bill|UNITED
STATES TREASURY|0.0000000000000000000|20240516|BILL||||||||
Footer - Count: 00000004, Facility: TRACE, File Created: 20230512154347
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
17
TRACE for Treasury Participant Daily List File Illustrating the Header and Footer
TRACE for Treasury Participant List File Illustrating the Header and Footer
list_dt|effective_dt|cd_description|old_mpid|old_dba|new_mpid|new_dba|rf_cd
09/09/2010|09/09/2010|Participant Addition|||HRBC|hurleyf test HRBC
mppweb|OTCE
09/09/2010|09/09/2010|Participant Addition|ABNE|ABNE TEST|||TRACE
09/09/2010|09/09/2010|Participant Addition|ABNF|ABNF TEST|||TRACE
09/09/2010|09/09/2010|Participant Addition|ABNB|ABN AMRO CLEARING CHICAGO
LLC|||TRACE
09/09/2010|09/09/2010|Participant Addition|ABNC|ABNC TEST|||TRACE
…
[snip]
…
09/09/2010|09/09/2010|Participant Deletion|AALC|THRIVENT INVESTMENT
MANAGEMENT CO2|||TRACE
Footer - Count: 00000014, Facility:TRACE, File Created: 20100910120732
mpid|dba_nm
AAAA|TEST
ABLE|NATIXIS BLEICHROEDER INC.
ABNA|ABN AMRO SECURITIES (USA) LLC
ABNB|ABN AMRO CLEARING CHICAGO LLC
ABNC|ABNC TEST
ABND|ABND TEST
ABNE|ABNE TEST
ABNG|ABNG TEST
ABPI|PAVEK INVESTMENTS INC.
…
[snip]
…
QUAL|QUAYLE & CO. SECURITIES
ROCK|ROCKWELL GLOBAL CAPITAL LLC
SCHO|SCHOFF & BAXTER, INC.
TMBR|TIMBER HILL LLC
UBSS|UBS SECURITIES LLC
WONG|A B WONG CAPITAL LLC
WTCO|WILLIAMS TRADING LLC
Footer - Count: 00000089, Facility: TRACE, File Created: 20100910121322
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
18
Appendices
Note: all codes/descriptions in the following appendices are subject to updates, as necessary.
Appendix 1 – Treasury Securities Coupon Type Codes and
Descriptions
Coupon Type Code
Coupon Type Description
DSC
Discount/Zero Coupon
FIX
Fixed Coupon
FLT
Floating Coupon
RNG
Range Coupon
STR
Stripped Coupon
TBP
To Be Priced Coupon
UNK
Unknown
VAR
Variable Coupon
Appendix 2 - Daily List Update Reason Codes and Descriptions
Update Reason Code
Update Reason Description
blank
No reason given
MOT
Moved from OTCE
DNY
Delisted from NYSE
DAX
Delisted from AMEX
DAR
Delisted from ARCA
DNQ
Delisted from NASDAQ
DEX
Delisted from Exchange
ISV
Ineligible – Sovereign
ICD
Ineligible – CD
ICR
Ineligible – Currency
IMM
Ineligible – Money Market
ITR
Ineligible – Treasury
IAI
Ineligible – Accredited Investor
IRS
Ineligible – Other
BR
Bankruptcy
LIQ
Liquidation
CAL
Called
RED
Redeemed
EXC
Exchanged
CAN
Cancelled
A/M
Acquisition/Merger
MAT
Matured
LNY
Listed on the NYSE
LAR
Listed on the NYSE ARCA
LAX
Listed on AMEX
LNQ
Listed on NASDAQ
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
19
*where OTH is used, please refer to the Event Comments field in the file (CMMNT_TX)
for additional information.
Update Reason Code
Update Reason Description
LCB
Listed on CBOE
ROB
Reportable to the OTCBB
RON
Reportable on the OTC NBB
RMS
Reportable to the MSRB
12J
12(j) Registration Revoked by the SEC
RNC
Regulatory Non Compliance
OTH
Other *
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
20
Programmatic Access Example(curl)
The following is a code excerpt to illustrate how to use the MPP Download site programmatically.
Example using the TS Security Master
#!/bin/bash
URL_REFRESH=https://apidownload.finratraqs.org/refresh [apidownload.finratraqs.org]
URL_DOWNLOAD=https://apidownload.finratraqs.org/DownloadHandler.ashx?action=DOWNLOA
D&file=TSMASTER&facility=TRACE [apidownload.finratraqs.org]
USER_NAME="Finrausr"
FAILEDSTATUS="HTTP/1.1 401 Token is inactive or expired."
FAILEDREFRESHSTATUS="Refresh Token is invalid or has expired."
update_tokens(){
# Get a new access_token
# install jq command - sudo apt-get install jq
tmp="$(mktemp)"
curl -s -X POST --url "${URL_REFRESH}" \
--header "content-type: application/x-www-form-
urlencoded" \
--data
"username=${USER_NAME}&refreshtoken=${refresh_token}" > "${tmp}"
read failedrefreshstatus < <(cat "${tmp}" | tr -d '\r')
#check if refresh token is invalid
if [ "${failedrefreshstatus}" = "${FAILEDREFRESHSTATUS}" ] ; then
echo "${failedrefreshstatus}"
echo ""
exit 1
fi
read refresh_token < <( cat "${tmp}" | jq .refresh_token | tr -d
'"' )
read access_token < <( cat "${tmp}" | jq .access_token | tr -d '"' )
#echo "${refresh_token}" > refresh_token.txt
echo "Requested new access token cached"
echo ""
echo "${access_token}" > access_token.txt
rm -f "${tmp}"
}
# The Refresh Token
read refresh_token < refresh_token.txt
echo "Your refresh token is ${refresh_token}"
echo ""
# The Access Token
access_token=""
if [ -f "access_token.txt" ]; then
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
21
read access_token < access_token.txt
fi
echo "Your current access token: ${access_token}"
echo ""
if [ -z "${access_token}" ]; then
echo "No cached access token; getting new access token!"
echo ""
update_tokens
read access_token < access_token.txt
echo "Your new access token: ${access_token}"
echo ""
fi
tmp="$(mktemp)"
echo "Validating access token..."
echo ""
#get curl header status for token validity
httpstatus=$(curl -s -I --url "${URL_DOWNLOAD}" \
--header "Authorization: Bearer ${access_token}" \
| awk 'NR==1{print $0} END {print $0}' | tr -d '\r')
#echo "$httpstatus" > httpstatus.txt
#echo "$FAILEDSTATUS" > failedstatus.txt
#check if token is invalid
if [ "${httpstatus}" = "${FAILEDSTATUS}" ] ; then
echo "Invalid/expired access token, requesting new access token!"
echo ""
update_tokens
read access_token < access_token.txt
echo "Your new access token: ${access_token}"
echo ""
fi
echo "Request download with access token!"
echo ""
#download file (this uses option -OJ, getting the file name from the content-
disposition
# if file exists, this will fail.)
curl -s -OJ -X POST --url "${URL_DOWNLOAD}" \
--header "Authorization: Bearer ${access_token}" \
--data "username=${USER_NAME}"
ls -lrt
#cat "${tmp}"
rm -f "${tmp}"
Web API Specifications for the TRACE Treasury Securities File Downloads
Version 4.1
22
Programmatic Access Example (C#, .NET)
The following is a code excerpt to illustrate how to use the MPP Download site programmatically. If you are
going to access the site with an application the first step is to download the NWSF client certificate using your
web browser. Install it in the browser then export the certificate from the browser, saving the certificate to a
location on the machine as an X905 certificate (.cer).
Example using the TS Security Master:
string Action = "DOWNLOAD";
string file = "TSMASTER";
string facility = "TRACE";
string site = "https:// download.finratraqs.org/DownloadHandler.ashx";
string query = string.Format("{0}?action={1}&file={2}&facility={3}", site,
Action, file, facility);
// Create request
HttpWebRequest webRequest = WebRequest.Create(query) as HttpWebRequest;
// Get cert and add to request
X509Certificate Cert =
X509Certificate.CreateFromCertFile("C:\\MPP\\cert\\mpp_cert.cer");
webRequest.ClientCertificates.Add(Cert);
webRequest.Method = "GET";
// Add nwsf user/password to request
NetworkCredential nwCredentials = new NetworkCredential("user", "pwd");
webRequest.Credentials = nwCredentials;
// Make the request
HttpWebResponse Response = (HttpWebResponse)webRequest.GetResponse();
// Fiddle with the header in the response to get the file name
int pos = Response.Headers["Content-Disposition"].IndexOf("TRACE");
string Filename = Response.Headers["Content-Disposition"].Substring(pos);
// Create a file to save it in ..
StreamWriter sw = new StreamWriter("C:\\MPP\\files\\" + Filename, false);
StreamReader sr = new StreamReader(Response.GetResponseStream(),
Encoding.Default);
int cnt;
char [] ReadBuf = new char[1024];
while ((cnt = sr.Read(ReadBuf, 0, 1024)) != 0)
{
sw.Write(ReadBuf);
}
