Address Directory API SEP

100 views
Skip to first unread message

Orbit Lens

unread,
Oct 9, 2020, 8:49:21 AM10/9/20
to Stellar Developers
Intro

Some of you know that we at StellarExpert maintain Directory that contains about 240 well-known Stellar addresses at the moment. Recently we extended our public API to support more advanced query syntax (like reverse lookup, search by a few addresses at a time) and added new address categories to address the increasing problem of scammers stealing people's money. Wide adoption of the proposed API might help wallets and exchanges to fight fraudulent activity by proactively blocking transfers to/from malicious accounts.

We also released a new interface that allows anyone to request Stellar address listing in a few clicks. This might be any address – anchor's issuer/distribution account, custodian exchange account, personal signing key, or an address spotted in illicit activity (scams, spamming, fraud, etc.) The Directory is moderated by StellarExpert team and SDF members – Kolten and Justin. We also hope that other reputable community members will join the moderators team in the future.

This "informational" SEP contains general specification of our free API for developers. 
Please feel free to comment. In particular, should we leave this standard as-is or provide the exact instructions for wallets and other API consumers of how to check an account and react on specific address tags?

------

Preamble
SEP: To Be Assigned 
Title: Address Directory API 
Author: OrbitLens<or...@stellar.expert> 
Track: Informational
Status: Draft
Created: 2020-09-04

Simple Summary

This standard describes an open REST API interface of the service that maintains a list of well-known Stellar account addresses.

Motivation

Stellar 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.

Abstract

The 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.

Specification

Each 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)
REST API specification

GET /directory/tags - list all available categories

Example:

curl https://api.stellar.expert/explorer/directory/tags

[
  {
    "name": "exchange",
    "description": "Centralized exchange account"
  },
  {
    "name": "anchor",
    "description": "Operational account of an anchor"
  },
  {
    "name": "issuer",
    "description": "Well known asset issuer account"
  },
  {
    "name": "wallet",
    "description": "Shared account that belongs to a wallet"
  },
  {
    "name": "custodian",
    "description": "Reserved, custodian account, or cold wallet"
  },
  {
    "name": "malicious",
    "description": "Account involved in theft/scam/spam/phishing"
  },
  {
    "name": "unsafe",
    "description": "Obsolete or potentially dangerous account"
  },
  {
    "name": "personal",
    "description": "Personal signing key or account address"
  },
  {
    "name": "sdf",
    "description": "Account under the custody of SDF"
  },
  {
    "name": "memo-required",
    "description": "Destination requires transaction memo"
  },
  {
    "name": "airdrop",
    "description": "Airdrop distribution account"
  },
  {
    "name": "obsolete-inflation-pool",
    "description": "Inflation pool distribution account (obsolete)"
  }
]

GET /directory - list all entries

This 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=2

{
  "_links": {
    "self": {
      "href": "/explorer/directory?sort=address&order=asc&limit=2"
    },
    "prev": {
      "href": "/explorer/directory?sort=address&order=desc&cursor=GA272U6UMNKYOBDCLH5CDAPZVDG4WAGJWFY2S2RV2DN6YSSOGYECEVOF&limit=2"
    },
    "next": {
      "href": "/explorer/directory?sort=address&order=asc&cursor=GA2VRL65L3ZFEDDJ357RGI3MAOKPJZ2Z3IJTPSC24I4KDTNFSVEQURRA&limit=2"
    }
  },
  "_embedded": {
    "records": [
      {
        "address": "GA272U6UMNKYOBDCLH5CDAPZVDG4WAGJWFY2S2RV2DN6YSSOGYECEVOF",
        "paging_token": "GA272U6UMNKYOBDCLH5CDAPZVDG4WAGJWFY2S2RV2DN6YSSOGYECEVOF",
        "domain": "",
        "name": "SCAM ACCOUNT",
        "tags": [
          "malicious"
        ]
      },
      {
        "address": "GA2VRL65L3ZFEDDJ357RGI3MAOKPJZ2Z3IJTPSC24I4KDTNFSVEQURRA",
        "paging_token": "GA2VRL65L3ZFEDDJ357RGI3MAOKPJZ2Z3IJTPSC24I4KDTNFSVEQURRA",
        "domain": "stellar.org",
        "name": "SDF Escrow Jan 1 2023",
        "tags": [
          "sdf",
          "custodian"
        ]
      }
    ]
  }

More query examples:

GET /directory/{address} - lookup specific Stellar account

Parameters:

  • address {String} - the address of the account to check

Example:

curl https://api.stellar.expert/explorer/directory/GA5XIGA5C7QTPTWXQHY6MCJRMTRZDOSHR6EFIBNDQTCQHG262N4GGKTM

{
  "address": "GA5XIGA5C7QTPTWXQHY6MCJRMTRZDOSHR6EFIBNDQTCQHG262N4GGKTM",
  "name": "Kraken",
  "domain": "kraken.com",
  "tags": [
    "exchange",
    "memo-required"
  ]
}

CORS, 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 Rationale

Ecosystem 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"

Reply all
Reply to author
Forward
0 new messages