Address Directory API SEP
Orbit Lens
This standard describes an open REST API interface of the service that maintains a list of well-known Stellar account addresses.
MotivationStellar address format works flawlessly as a unique account identifier, but from the user's perspective, such long alphanumeric sequences often look indistinguishable from one another. The address itself does not provide any additional info about the person or entity behind it. In practice, it means that users often can't identify the source/destination of a payment operation even in their own transaction history.
SEP-0001 defines a standard way for public entities' self-identification, which partially addresses the situation. However, not all exchanges and other apps follow the standard. Moreover, information for many now-defunct anchors and apps can't be retrieved since their websites don't work anymore (stellar.toml is unavailable). The same goes for obsolete exchange deposit accounts where people may send funds by mistake.
Custodian accounts that rely on transaction memos make another example of entities ignoring ecosystem guidelines. Only a few exchanges adopted quite a straightforward SEP-0029 standard, so the problem of missing memos is still relevant. A systematized list of accounts tagged as "memo-required" proved to be a convenient solution that helps to check memo prerequisites for custodial wallets regardless of their adherence to specifications.
While the latter two examples at least partially can be sorted out using existing approaches given that entities behind those accounts put some efforts into this, there is a category of addresses that will never be mapped that way. The problem of people loosing their money to various frauds is quite crucial – law enforcement agencies often can't help in such cases. Accounts spotted in scam schemes or other illicit activity can be identified and blocked only as a result of joint community effort. If the community and exchanges agree on using Directory API to prevent transfers to/from addresses marked as malicious, it will significantly complicate further transfers of stolen funds while providing crucial information for compliance checks.
StellarExpert Directory aims to address the problems described above by introducing an open REST API interface for the curated list of categorized addresses.
AbstractThe described curated Stellar addresses list provides publicly available information about well-known accounts via a set of open REST API endpoints. Address Directory API is publicly available for everyone, free of charge.
SpecificationEach directory entry contains the following set of fields:
- address - Stellar address of the account
- name - short display name
- domain - domain of the public entity operating the account
- tags - array of account tags (categories)
Example:
curl https://api.stellar.expert/explorer/directory/tagsThis API endpoint follows Stellar Horizon API response format convention. A response result contains records and navigation links.
Optional query parameters:
- address {Array<String>} - filters results by addresses list (up to 50 per request)
- tag {Array<String>} - applies a filter by tags
- search {String} - applies a full-test search filter by entry address, name, or domain
- cursor {String} - address from which to continue search (paging_token value from a results set)
- order {String} - "asc" or "desc", controls results order
- limit {Number} - data page size (10 entries per page by default)
Example:
curl https://api.stellar.expert/explorer/directory?limit=2More query examples:
- Fetch information about multiple accounts in one call:
curl -g "https://api.stellar.expert/explorer/directory?address[]=GA6HCMBLTZS5VYYBCATRBRZ3BZJMAFUDKYYF6AH6MVCMGWMRDNSWJPIH&address[]=GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S" - Search for Kraken's deposit account
curl "https://api.stellar.expert/explorer/directory?search=kraken" - Find accounts tagged as malicious or unsafe:
curl -g "https://api.stellar.expert/explorer/directory?tag[]=malicious&tag[]=unsafe" - Lookup addresses reported for "staking"-related scams:
curl -g "https://api.stellar.expert/explorer/directory?tag[]=malicious&search=stacking"
Parameters:
- address {String} - the address of the account to check
Example:
curl https://api.stellar.expert/explorer/directory/GA5XIGA5C7QTPTWXQHY6MCJRMTRZDOSHR6EFIBNDQTCQHG262N4GGKTMCORS, Rate Limiting and Caching Considerations
All described API endpoints have CORS headers enabled, so they can be used directly from any website.
The effective API request rate is limited to 5 requests per second for each individual IP. Please consider response caching or group queries on your side in case of heavy utilization.
Design RationaleEcosystem wallets and anchors have been using this API since 2018 when it was first introduced.
In order to keep the format of returned entries as lightweight and unambiguous as possible, Directory contains only the bare minimum of important information.
Security Concerns"N/A"