Merge pull request #344 from porters-xyz/tkn-api

Tkn api
porters-xyz · Aug 21, 2024 · 396df36 · 396df36
2 parents 22384a5 + dd66426
commit 396df36
Show file tree

Hide file tree

Showing 14 changed files with 14,716 additions and 1 deletion.
diff --git a/docs/pages/APIs/TKN/_meta.json b/docs/pages/APIs/TKN/_meta.json
@@ -0,0 +1,8 @@
+{
+    "intro": "Introduction",
+    "get_contract_address": "Get Contract Address",
+    "get_contract_metadata": "Get Contract Metadata",
+    "get_token_balance": "Get Token Balance",
+    "get_token_price_data": "Get Token Price Data"
+  }
+
diff --git a/docs/pages/APIs/TKN/get_contract_address.mdx b/docs/pages/APIs/TKN/get_contract_address.mdx
@@ -0,0 +1,55 @@
+# Get Contract Address
+`GET /token/:portersAppId/contract-address/:ticker`
+
+## Description
+Fetches the Ethereum contract address associated with the specified ENS name.
+
+## Parameters
+- **portersAppId (string)**: The application ID used to authenticate the request with the provider.
+- **ticker (string)**: The ticker symbol of the token, expected to resolve to an ENS name (e.g., "usdc" for "usdc.tkn.eth").
+
+## Response
+
+### Success (200 OK)
+
+```
+{
+  "response": {
+    "address": "0xAbC123...",
+  },
+  "status": "success"
+}
+```
+
+### Error (4xx/5xx)
+
+```
+{
+  "response": {
+    "error": "Error message describing what went wrong."
+  },
+  "status": "error"
+}
+```
+
+## Possible Errors
+- **400 BAD REQUEST**: Returned when the input parameters are missing or invalid.
+- **404 NOT FOUND**: Returned when the ENS name cannot be resolved to a contract address.
+- **500 INTERNAL SERVER ERROR**: Returned when an unexpected error occurs, such as network failures or unhandled exceptions.
+
+# Example
+
+## Request
+
+`GET /token/myAppId/contract-address/usdc`
+
+## Response
+
+```
+{
+    "response": {
+        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+    },
+    "status": "success"
+}
+```
diff --git a/docs/pages/APIs/TKN/get_contract_metadata.mdx b/docs/pages/APIs/TKN/get_contract_metadata.mdx
@@ -0,0 +1,115 @@
+# Get Contract Metadata
+`GET /token/:portersAppId/:ticker/metadata`
+
+## Description
+Fetches metadata for a specific token based on the ticker symbol. The metadata includes details like contract address, token name, description, associated URLs, and addresses on various blockchains.
+
+## Parameters
+**portersAppId (string)**: The application ID used to authenticate the request with the provider.
+**ticker (string)**: The ticker symbol of the token, used to fetch the corresponding metadata.
+
+## Response
+
+### Success (200 OK)
+
+```
+{
+  "response": {
+    "info": {
+      "contractAddress": "0xAbC123...",
+      "name": "Token Name",
+      "url": "https://token.website",
+      "avatar": "https://token.avatar.url",
+      "description": "Token description",
+      "notice": "Important notice about the token",
+      "version": "1.0",
+      "decimals": 18,
+      "twitter": "https://twitter.com/token",
+      "github": "https://github.com/token",
+      "dweb": "https://dweb.link/token",
+      "addresses": {
+        "eth": "0xAbC123...",
+        "arbitrum": "0xArb123...",
+        "avax": "0xAvax123...",
+        "base": "0xBase123...",
+        "bsc": "0xBsc123...",
+        "cronos": "0xCro123...",
+        "fantom": "0xFtm123...",
+        "gnosis": "0xGno123...",
+        "goerli_testnet": "0xGoerli123...",
+        "near": "0xNear123...",
+        "optimism": "0xOp123...",
+        "polygon": "0xMatic123...",
+        "sepolia_testnet": "0xSepolia123...",
+        "solana": "0xSol123...",
+        "tron": "0xTrx123...",
+        "ziliqa": "0xZil123..."
+      }
+    }
+  },
+  "status": "success"
+}
+```
+
+### Error (4xx/5xx)
+
+```
+{
+  "response": {
+    "error": "Error message describing what went wrong."
+  },
+  "status": "error"
+}
+```
+
+## Possible Errors
+- 400 BAD REQUEST: Returned when the input parameters are missing or invalid.
+- 404 NOT FOUND: Returned when the ENS name cannot be resolved to a contract address.
+- 500 INTERNAL SERVER ERROR: Returned when an unexpected error occurs, such as issues fetching contract data or other unhandled exceptions.
+
+# Example
+
+## Request
+
+`GET /token/myAppId/usdt/metadata`
+
+## Response
+
+```
+{
+    "response": {
+        "info": {
+            "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+            "name": "Tether",
+            "url": "https://tether.to/",
+            "avatar": "https://gateway.tkn.xyz/ipfs/bafybeifyk25azxxtmoh52poyii5w2vmvcn7jtiecnqhilfmlriqs6t4jia",
+            "description": "Digital Dollar Token",
+            "notice": "",
+            "version": "0.0.1",
+            "decimals": "6",
+            "twitter": "tether_to",
+            "github": "",
+            "dweb": "0x",
+            "addresses": {
+                "eth": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+                "arbitrum": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+                "avax": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
+                "base": "0x0000000000000000000000000000000000000000",
+                "bsc": "0x55d398326f99059fF775485246999027B3197955",
+                "cronos": "0x66e428c3f67a68878562e79A0234c1F83c208770",
+                "fantom": "0x049d68029688eAbF473097a2fC38ef61633A3C7A",
+                "gnosis": "0x4ECaBa5870353805a9F068101A40E0f32ed605C6",
+                "goerli_testnet": "0x0000000000000000000000000000000000000000",
+                "near": "dac17f958d2ee523a2206206994597c13d831ec7.factory.bridge.near",
+                "optimism": "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58",
+                "polygon": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
+                "sepolia_testnet": "0x0000000000000000000000000000000000000000",
+                "solana": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+                "tron": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+                "ziliqa": "0x"
+            }
+        }
+    },
+    "status": "success"
+}
+```
diff --git a/docs/pages/APIs/TKN/get_token_balance.mdx b/docs/pages/APIs/TKN/get_token_balance.mdx
@@ -0,0 +1,86 @@
+# Get Token Balance
+`GET /token/:portersAppId/:ticker/balance`
+
+## Description
+Fetches the balance of a specific token for a given network and user account.
+
+## Parameters
+- **portersAppId (string)**: The application ID used to authenticate the request with the provider.
+- **ticker (string)**: The ticker symbol of the token, used to fetch the corresponding balance.
+- **network (string)**: The blockchain network on which the token resides (e.g., "eth", "bsc", "polygon"). Refer to Supported Networks section below.
+- **address (string)**: The address of the user account whose token balance is to be retrieved.
+
+### Supported Networks
+- *eth*, Ethereum Mainnet
+- *arbitrum*, Arbitrum
+- *avax*, Avalanche C-Chain
+- *base*, Base Mainnet
+- *bsc*, Binance Smart Chain
+- *gnosis*, Gnosis Mainnet
+- *optimism*, Optimism Mainnet
+- *polygon*, Polygon
+- *sepolia-testnet*, Sepolia Testnet
+
+
+## Response
+
+### Success (200 OK)
+
+```
+{
+    "response": {
+        "token": {
+            "token": "USDC",
+            "network": "eth",
+            "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+        },
+        "account": {
+            "address": "0x1234...abcd",
+            "balance": "1000.00"
+        }
+    },
+"status": "success"
+}
+```
+
+### Error (4xx/5xx)
+
+```
+{
+    "response": {
+        "error": "Error message describing what went wrong."
+    },
+    "status": "error"
+}
+```
+
+
+## Possible Errors
+- **400 BAD REQUEST**: Returned when the network is not supported for the specified token.
+- **404 NOT FOUND**: Returned when the ENS name cannot be resolved to a contract address.
+- **500 INTERNAL SERVER ERROR**: Returned when an unexpected error occurs, such as issues fetching the token balance or other unhandled exceptions.
+
+# Example
+
+## Request
+
+`GET /token/myAppId/usdc/balance?network=eth&address=0x1234...abcd`
+
+## Response
+
+```
+{
+    "response": {
+        "token": {
+            "token": "USDC",
+            "network": "eth",
+            "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+        },
+        "account": {
+            "address": "0x1234...abcd",
+            "balance": "1000.00"
+        }
+    },
+    "status": "success"
+}
+```
diff --git a/docs/pages/APIs/TKN/get_token_price_data.mdx b/docs/pages/APIs/TKN/get_token_price_data.mdx
@@ -0,0 +1,87 @@
+# Get Token Price Data
+`GET /token/:portersAppId/:ticker/price`
+
+## Description
+Fetches the current price of a specific token against Wrapped Ether (WETH) on Uniswap V3, using the 0.3% fee tier.
+
+## Parameters
+- portersAppId (string): The application ID used to authenticate the request with the provider.
+- ticker (string): The ticker symbol of the token, used to fetch the corresponding price data.
+
+## Response
+
+### Success (200 OK)
+
+```
+{
+  "response": {
+    "message": "The price of TKN is 0.123456 WETH on Uniswap.",
+    "token0": {
+      "chainId": 1,
+      "address": "0xAbC123...",
+      "decimals": 18,
+      "symbol": "TKN",
+      "name": "Token Name"
+    },
+    "token1": {
+      "chainId": 1,
+      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+      "decimals": 18,
+      "symbol": "WETH",
+      "name": "Wrapped Ether"
+    },
+    "price": "0.123456"
+  },
+  "status": "success"
+}
+```
+
+### Error (4xx/5xx)
+
+```
+{
+  "response": {
+    "error": "Error message describing what went wrong."
+  },
+  "status": "error"
+}
+```
+
+## Possible Errors
+- **404 NOT FOUND**: Returned when the ENS name cannot be resolved to a contract address or if the pool does not exist for the provided token pair and fee tier.
+- **500 INTERNAL SERVER ERROR**: Returned when there is a problem fetching data from the Uniswap pool, such as:
+  - The pool does not exist for the provided token pair and fee tier.
+  - An invalid tick value is received from the pool contract.
+  - Any other unexpected error occurs during the process.
+
+# Example
+
+## Request
+
+`GET /token/myAppId/usdc/price`
+
+## Response
+
+```
+{
+  "response": {
+    "message": "The price of USDC is 0.123456 WETH on Uniswap.",
+    "token0": {
+      "chainId": 1,
+      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      "decimals": 6,
+      "symbol": "USDC",
+      "name": "USD Coin"
+    },
+    "token1": {
+      "chainId": 1,
+      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+      "decimals": 18,
+      "symbol": "WETH",
+      "name": "Wrapped Ether"
+    },
+    "price": "0.999999"
+  },
+  "status": "success"
+}
+```
diff --git a/docs/pages/APIs/TKN/intro.mdx b/docs/pages/APIs/TKN/intro.mdx
@@ -0,0 +1,11 @@
+# Token Name Service
+
+The Token Name Serivce (TKN) is a service that uses ENS to facilitate the creation of shared datasets containing information about tokens.
+
+For more information visit [https://tkn.xyz/](https://tkn.xyz/).
+
+# Porters App ID
+
+Use of this API requires a Porters App to be set up in the Porters backend. The App Id can then be passed as the `portersAppId` parameter.
+
+Since this serice calls multiple chains, it is advisable not to set up any rules that limit chain usage on the App Id that will be used for this API.
diff --git a/docs/pages/APIs/_meta.json b/docs/pages/APIs/_meta.json
@@ -0,0 +1,4 @@
+{
+    "about_apis": "About Porters APIs"
+  }
+
diff --git a/docs/pages/APIs/about_apis.mdx b/docs/pages/APIs/about_apis.mdx
@@ -0,0 +1,11 @@
+# API Documentation
+
+Porters intends to offer APIs that leverage its Web3 infrastructure for easy access to Web3 services and solutions.
+
+This section is intended to document these implementations.
+
+## Available APIs
+1. TKN Api
+
+# Need an API?
+Have an idea or need for an API? Feel free to reach out!