@covalenthq/client-sdk 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +158 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,158 @@
|
|
|
1
|
-
# covalent-api-sdk-js
|
|
1
|
+
# covalent-api-sdk-js
|
|
2
|
+
|
|
3
|
+
The Covalent API SDK is currently supported for Javascript only.
|
|
4
|
+
|
|
5
|
+
The Covalent SDK supports all chains across Mainnets and Testnets. List of supported Networks can be found on our [Supported Networks page](https://www.covalenthq.com/docs/networks/)
|
|
6
|
+
|
|
7
|
+
> **Name Resolution**
|
|
8
|
+
>
|
|
9
|
+
> The Covalent SDK supports address resolution natively allowing an ENS, RNS, Lens Handle or Unstoppable Domains address to be passed in directly for all our endpoints.
|
|
10
|
+
|
|
11
|
+
## Getting started
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
npm install @covalenthq/client-sdk
|
|
15
|
+
```
|
|
16
|
+
or
|
|
17
|
+
```
|
|
18
|
+
yarn add @covalenthq/client-sdk
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
After installing the app, you can then import and use the SDK:
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { Client } from "@covalenthq/client-sdk";
|
|
25
|
+
|
|
26
|
+
const ApiServices = async () => {
|
|
27
|
+
const client = new Client("YOUR_API_KEY"); // Replace with your Covalent API key.
|
|
28
|
+
const resp = await client.BalancesService.getTokenBalances("eth-mainnet", "WALLET_ADDRESS"); // Example call, refer to API Docs for required paramaters or click into the method `getTokenBalances` to see the accepted parameter arguments
|
|
29
|
+
console.log(resp.data);
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
> **Creating a unique Covalent API Key**
|
|
34
|
+
>
|
|
35
|
+
> To create your own API key, **[sign up for an Covalent account here](https://www.covalenthq.com/platform/auth/register/)** and use the key created under the [API Keys](https://www.covalenthq.com/platform/apikey/) tab.
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
## How to use the Covalent SDK
|
|
39
|
+
|
|
40
|
+
The Covalent SDK provides comprehensive support for all Class A, Class B, and Pricing endpoints grouped under various Services, offering a wide range of functionalities and capabilities:
|
|
41
|
+
|
|
42
|
+
- `ApprovalService`: Access to the Covalent's getApprovals endpoint
|
|
43
|
+
- `BalancesService`: Access to the Covalent's balances endpoints
|
|
44
|
+
- `BaseServices`: Access to the Covalent's log events, chain, and block endpoints
|
|
45
|
+
- `LogEventService`: Access to the Covalent's get logs endpoint
|
|
46
|
+
- `NameResolverService`: Access to the Covalent's get resolved address for registered address endpoint
|
|
47
|
+
- `NftService`: Access to the Covalent's NFT endpoints
|
|
48
|
+
- `PricingService`: Access to the Covalent's get historical token prices endpoint
|
|
49
|
+
- `TransactionsService`: Access to the Covalent's transactions endpoints (with pagination)
|
|
50
|
+
- `XykService`: Access to the Covalent's Xy=k endpoints
|
|
51
|
+
|
|
52
|
+
### ApprovalService
|
|
53
|
+
|
|
54
|
+
The `ApprovalService` class contains the getApprovals() endpoint, refer to the [getApprovals endpoint on our API docs](https://www.covalenthq.com/docs/api/security/get-token-approvals-for-address/).
|
|
55
|
+
|
|
56
|
+
- `getApprovals()`: Get a list of approvals across all token contracts categorized by spenders for a wallet’s assets.
|
|
57
|
+
|
|
58
|
+
### BalancesService
|
|
59
|
+
|
|
60
|
+
The `BalancesService` class contains the balances endpoints. Listed below are the supported endpoints, also refer to our api docs under the Balances section in our class A endpoints.
|
|
61
|
+
|
|
62
|
+
- `getTokenBalances()`: Fetch the native, fungible (ERC20), and non-fungible (ERC721 & ERC1155) tokens held by an address. Response includes spot prices and other metadata.
|
|
63
|
+
- `getAddressPortfolio()`: Render a daily portfolio balance for an address broken down by the token. The timeframe is user-configurable, defaults to 30 days.
|
|
64
|
+
- `getErc20Transfers()`: Render the transfer-in and transfer-out of a token along with historical prices from an address.
|
|
65
|
+
- `getTokenHoldersV2()`: Get a list of all the token holders for a specified ERC20 or ERC721 token. Returns historic token holders when block-height is set (defaults to latest). Useful for building pie charts of token holders.
|
|
66
|
+
|
|
67
|
+
### BaseServices
|
|
68
|
+
|
|
69
|
+
The `BaseServices` class contains the log events, chain, and block endpoints. Listed below are the supported endpoints, also refer to our api docs under the Base section in our class A endpoints.
|
|
70
|
+
|
|
71
|
+
- `getBlock()`: Fetch and render a single block for a block explorer.
|
|
72
|
+
- `getBlockHeights()`: Get all the block heights within a particular date range. Useful for rendering a display where you sort blocks by day.
|
|
73
|
+
- `getLogEventsByAddress()`: Get all the event logs emitted from a particular contract address. Useful for building dashboards that examine on-chain interactions.
|
|
74
|
+
- `getLogEventsByTopicHash()`: Get all event logs of the same topic hash across all contracts within a particular chain. Useful for cross-sectional analysis of event logs that are emitted on-chain.
|
|
75
|
+
- `getAllChains()`: Used to build internal dashboards for all supported chains on Covalent.
|
|
76
|
+
- `getAllChainStatus()`: Used to build internal status dashboards of all supported chains.
|
|
77
|
+
|
|
78
|
+
### LogEventService
|
|
79
|
+
|
|
80
|
+
The `LogEventService` class contains the getLogs() endpoint. Refer to the [getLogs endpoint on our API docs](https://www.covalenthq.com/docs/api/base/get-logs/).
|
|
81
|
+
|
|
82
|
+
- `getLogs()`: Get all the event logs of the latest block, or for a range of blocks. Includes sender contract metadata as well as decoded logs.
|
|
83
|
+
|
|
84
|
+
### NameResolverService
|
|
85
|
+
|
|
86
|
+
The `NameResolverService` class contains the getResolvedAddress() endpoint. Refer to the [getResolvedAddress endpoint on our API docs](https://www.covalenthq.com/docs/api/base/get-resolved-address-for-registered-address/).
|
|
87
|
+
|
|
88
|
+
- `getResolvedAddress()`: Used to resolve ENS, RNS and Unstoppable Domains addresses.
|
|
89
|
+
|
|
90
|
+
### NftService
|
|
91
|
+
|
|
92
|
+
The `NftService` class contains the NFT endpoints. Listed below are the supported endpoints, also refer to our api docs under the NFT section in our class A endpoints.
|
|
93
|
+
|
|
94
|
+
- `getChainCollections()`: Used to fetch the list of NFT collections with downloaded and cached off chain data like token metadata and asset files.
|
|
95
|
+
- `getNftsForAddress()`: Used to render the NFTs (including ERC721 and ERC1155) held by an address.
|
|
96
|
+
- `getTokenIdsForContractWithMetadata()`: Get NFT token IDs with metadata from a collection. Useful for building NFT card displays.
|
|
97
|
+
- `getNftMetadataForGivenTokenIDForContract()`: Get a single NFT metadata by token ID from a collection. Useful for building NFT card displays.
|
|
98
|
+
- `getNftTransactionsForContractTokenId()`: Get all transactions of an NFT token. Useful for building a transaction history table or price chart.
|
|
99
|
+
- `getTraitsForCollection()`: Used to fetch and render the traits of a collection as seen in rarity calculators.
|
|
100
|
+
- `getAttributesForTraitInCollection()`: Used to get the count of unique values for traits within an NFT collection.
|
|
101
|
+
- `getCollectionTraitsSummary()`: Used to calculate rarity scores for a collection based on its traits.
|
|
102
|
+
- `checkOwnershipInNft()`: Used to verify ownership of NFTs (including ERC-721 and ERC-1155) within a collection.
|
|
103
|
+
- `checkOwnershipInNftForSpecificTokenId()`: Used to verify ownership of a specific token (ERC-721 or ERC-1155) within a collection.
|
|
104
|
+
- `getNftExternalMetadataForContract()`: Get a single NFT with metadata by token ID from a collection. Useful for building NFT card displays.
|
|
105
|
+
|
|
106
|
+
### PricingService
|
|
107
|
+
|
|
108
|
+
The `PricingService` class contains the getTokenPrices() endpoint. Refer to the [getTokenPrices endpoint on our API docs](https://www.covalenthq.com/docs/api/pricing/get-historical-token-prices/).
|
|
109
|
+
|
|
110
|
+
- `getTokenPrices()`: Get historic prices of a token between date ranges. Supports native tokens.
|
|
111
|
+
|
|
112
|
+
### TransactionsService
|
|
113
|
+
|
|
114
|
+
The `TransactionsService` class contains the transactions endpoint. Listed below are the supported endpoints, also refer to our api docs under the Transactions section in our class A endpoints.
|
|
115
|
+
|
|
116
|
+
- `getRecentTransactionsForAddress()`: Fetch and render the most recent transactions involving an address. Frequently seen in wallet applications.
|
|
117
|
+
- `getTransaction()`: Fetch and render a single transaction including its decoded log events. Additionally return semantically decoded information for DEX trades, lending and NFT sales.
|
|
118
|
+
- `getTransactionsForBlock()`: Fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.
|
|
119
|
+
- `getTransactionSummary()`: Fetch the earliest and latest transactions, and the transaction count for a wallet. Calculate the age of the wallet and the time it has been idle and quickly gain insights into their engagement with web3.
|
|
120
|
+
|
|
121
|
+
### XykService
|
|
122
|
+
|
|
123
|
+
The `XykService` class contains the Xy=k endpoints. Listed below are the supported endpoints, also refer to our api docs under the XY=K section in our class B endpoints.
|
|
124
|
+
|
|
125
|
+
- `getPools()`: Get all the pools of a particular DEX. Supports most common DEXs (Uniswap, SushiSwap, etc), and returns detailed trading data (volume, liquidity, swap counts, fees, LP token prices).
|
|
126
|
+
- `getPoolByAddress()`: Get the 7 day and 30 day time-series data (volume, liquidity, price) of a particular liquidity pool in a DEX. Useful for building time-series charts on DEX trading activity.
|
|
127
|
+
- `getAddressExchangeBalances()`: Return balance of a wallet/contract address on a specific DEX.
|
|
128
|
+
- `getNetworkExchangeTokens()`: Get the balance of a wallet address in a DEX. Useful for finding out user balances locked up in DEX pools.
|
|
129
|
+
- `getSupportedDEXes()`: Get all the supported DEXs available for the xy=k endpoints, along with the swap fees and factory addresses.
|
|
130
|
+
- `getSingleNetworkExchangeToken()`: Get historical daily swap count for a single network exchange token.
|
|
131
|
+
- `getTransactionsForAccountAddress()`: Get all the DEX transactions of a wallet. Useful for building tables of DEX activity segmented by wallet.
|
|
132
|
+
- `getTransactionsForTokenAddress()`: Get all the transactions of a token within a particular DEX. Useful for getting a per-token view of DEX activity.
|
|
133
|
+
- `getTransactionsForExchange()`: Get all the transactions of a particular DEX liquidity pool. Useful for building a transactions history table for an individual pool.
|
|
134
|
+
- `getEcosystemChartData()`: Get a 7d and 30d time-series chart of DEX activity. Includes volume and swap count.
|
|
135
|
+
- `getHealthData()`: Ping the health of xy=k endpoints to get the synced block height per chain.
|
|
136
|
+
|
|
137
|
+
### How pagination works
|
|
138
|
+
|
|
139
|
+
The Covalent getRecentTransactionsForAddress() endpoint is currently the only endpoint that supports pagination which return 100 results per page. To get the next page, it uses a link url that is grabbed from the previous call. Here's an example of how to paginate through all recent transactions on the ethereum blockchain for the demo's ENS address:
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
import { Client } from "@covalenthq/client-sdk";
|
|
143
|
+
|
|
144
|
+
const ApiServices = async () => {
|
|
145
|
+
const client = new Client("YOUR_API_KEY"); // Replace with your Covalent API key.
|
|
146
|
+
for await (const resp of client.TransactionsService.getRecentTransactionsForAddress("eth-mainnet", "demo.eth")) {
|
|
147
|
+
console.log("resp", resp);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Retry Mechanism
|
|
153
|
+
|
|
154
|
+
Each endpoint is equipped with an exponential backoff algorithm that exponentially extends the wait time between retries, making up to a `maximum of 5` retry attempts only.
|
|
155
|
+
|
|
156
|
+
## Documentation
|
|
157
|
+
|
|
158
|
+
The Covalent API SDK documentation is integrated within the source code through `tsdoc` comments. When utilizing an Integrated Development Environment (IDE), the SDK provides generated types and accompanying documentation for seamless reference and usage.
|