Querying the Dataset
Overview
The Token Name Service uses ENS, and can be queried anywhere .eth domains are supported
The Token name set is persisted as subdomains of the .tkn.eth domain
For instance, the contract for USDC can be found at usdc.tkn.eth and Wrapped Bitcoin at wbtc.tkn.eth
Descriptive metadata can be found on chain in each token's ENS resolver. Including name, description, avatar, url, dweb, decimals, notice, version, twitter, & github.
The TNS.sol contract exposes additional queries; such as: fetch all metadata, fetch token contracts on all chains, and token balance for address. TNS.sol is hosted at tkn.eth
Get token contract address
Retrieves the address where the token contract resides.
Useful for converting a user supplied token symbol into an actionable contract.
await provider.resolveName("uni.tkn.eth");
// '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984'Fetch the mainnet contract address for WBTC
import { useEnsAddress } from 'wagmi'
function App() {
const { data, isError, isLoading } = useEnsAddress({
name: 'wbtc.tkn.eth',
})
if (isLoading) return <div>Fetching address…</div>
if (isError) return <div>Error fetching address</div>
return <div>Address: {data}</div>
}
// Returns data: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599'pragma solidity ^0.8.4;
contract HelloTKN {
ITKN tkn;
constructor() {
tkn = ITKN(0xc11BA824ab2cEA5E701831AB87ed43eb013902Dd);
}
// Get an account's balance from a ticker symbol
function balanceForAddress(address user, string calldata tickerSymbol) public view returns (uint) {
// Fetch the token contract address with ticker:
address contractAddress = tkn.addressFor(tickerSymbol);
IERC20 tokenContract = IERC20(contractAddress);
return tokenContract.balanceOf(user);
}
}
// Required Interfaces
interface ITKN {
struct TokenInfo {
address contractAddress;
string name;
string url;
string avatar;
string description;
string notice;
string version;
string decimals;
string twitter;
string github;
bytes dweb;
}
function addressFor(string calldata _name) external view returns (address);
function infoFor(string calldata _name) external view returns (TokenInfo memory);
function gasEfficientFetch(bytes32 namehash) external view returns (address);
function balanceWithTicker(address user, string calldata tickerSymbol) external view returns (uint);
}
interface IERC20 {
function balanceOf(address account) external view returns (uint256);
function transfer(address recipient, uint256 amount) external returns (bool);
} Get token by contract address
Reverse resolution by token contract address is now available
Query <tokenAddress>.<chain>.tkn.eth to fetch the metadata for that token
Example: 0x78b3C724A2F663D11373C4a1978689271895256f.base.tkn.eth ($TKN on Base) will resolve the data for the $TKN token
Get single datapoint
Get one of the datapoints available for each token.
Pulls a single datapoint, such as a name or description.
To see the available data types visit: https://docs.tkn.xyz/developers/dataset
Get all token info
Retrieve all datapoints for a token, excluding the sidechain contract addresses.
Useful for fetching all token data in a single query.
Get all token info and sidechain contract addresses
Retrieve all token info and it's sidechain contract addresses.
Useful for fetching all known data about a token in a single query.
Decoding non-EVM and dweb responses:
Non-EVM contract addresses can be decoded with https://www.npmjs.com/package/@ensdomains/address-encoder
addressEncoder.formatsByName['SOL'].encoder(Buffer.from(tokenData.sol_address.substring(2), 'hex'))
And the dweb IPFS CID can be decoded with
https://github.com/pldespaigne/content-hash#contenthashdecode-contenthash----string
Get all sidechain contract addresses
Retrieve all token sidechain contract addresses.
Useful for a token's contract addresses for all chains in a single query.
Decoding non-EVM contract addresses:
Non-EVM contract addresses can be decoded with https://www.npmjs.com/package/@ensdomains/address-encoder
addressEncoder.formatsByName['SOL'].encoder(Buffer.from(tokenData.sol_address.substring(2), 'hex'))
Get tokens owned by an address
Lookup how many tokens an address owns, using a token symbol.
Helpful for looking up an ERC20 account balance without having to fetch the token contract address separately.
Get all TKN tokens
There are multiple ways to fetch the complete list of tokens
Registry.tkn.eth: a simple JSON array with the symbols for all listed tokens. The current source of truth for TKN listings. Can be fetched with an IPFS dweb resolver, or eth.limo. https://registry.tkn.eth.limo/
TheGraph: TKN now has it's very own subgraph. Can conveniently produce all tokens and metadata in a single query.
Use this TKN Subgraph query to fetch all tokens and metadata at once:
And this query can be used to fetch a single token:
TokenList: Tokenlists.org formatted list. Published at
list.tkn.eth. View at: https://tokenlists.org/token-list?url=list.tkn.eth
Last updated
Was this helpful?