Merge pull request #488 from alchemyplatform/shreyas/new-params

add params to token and price APIs; update naming for clarity

Author: shreyas-v-agnihotri

data/assets/nfts/by-address.yaml

@@ -1,6 +1,6 @@
 summary: NFTs By Wallet
 description: >
-  Retrieves all NFTs currently owned by multiple addresses using network and address pairs. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens).
+    Fetches NFTs for multiple wallet addresses and networks. Returns a list of NFTs and metadata for each wallet/network combination. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens).
 tags: ["📚 Portfolio APIs"]
 x-readme:
   samples-languages:

data/assets/nfts/contracts/by-address.yaml

@@ -1,6 +1,6 @@
-summary: Contracts By Wallet
+summary: NFT Collections By Wallet
 description: >
-  Retrieves all NFT contracts currently owned by multiple addresses using network and address pairs. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens).
+    Fetches NFT collections (contracts) for multiple wallet addresses and networks. Returns a list of collections and metadata for each wallet/network combination. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens).
 tags: ["📚 Portfolio APIs"]
 x-readme:
   samples-languages:

data/assets/tokens/balances/by-address.yaml

@@ -1,6 +1,6 @@
 summary: Token Balances By Wallet
 description: >
-  Fetches current balances for multiple addresses using network and address pairs. Returns a list of token balances, each containing the network and address. This endpoint is supported on Ethereum, Solana, and 30+ EVM chains. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens)
+  Fetches fungible tokens (native and ERC-20) for multiple wallet addresses and networks. Returns a list of tokens with balances for each wallet/network combination. This endpoint is supported on Ethereum, Solana, and 30+ EVM chains. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens)
 tags: ["📚 Portfolio APIs"]
 x-readme:
   samples-languages:

data/assets/tokens/by-address.yaml

@@ -1,6 +1,6 @@
 summary: Tokens By Wallet
 description: >
-  Fetches current balances, prices, and metadata for multiple addresses using network and address pairs. Returns a list of token balances, each containing the network and address. This endpoint is supported on Ethereum, Solana, and 30+ EVM chains. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens).
+  Fetches fungible tokens (native and ERC-20) for multiple wallet addresses and networks. Returns a list of tokens with balances, prices, and metadata for each wallet/network combination. This endpoint is supported on Ethereum, Solana, and 30+ EVM chains. See the full list of supported networks [here](https://dashboard.alchemy.com/chains?service=token-api&utm_source=readme&utm_medium=link&utm_campaign=docs_method_chains_link_v1_tokens).
 tags: ["📚 Portfolio APIs"]
 x-readme:
   samples-languages:

data/transactions/history/by-address.yaml

@@ -1,6 +1,6 @@
-summary: Transaction History By Wallet
+summary: Transactions By Wallet
 description: >
-  Fetches all transactions addresses using network and address pairs (currently limited to 1 in BETA) Returns a list of transaction objects. This endpoint will be supported on Ethereum, Solana, and 30+ EVM chains (currently limited to ETH and Base)
+  Fetches all historical transactions (internal & external) for multiple wallet addresses and networks. Returns a list of transaction objects with metadata and log information. This endpoint will be supported on Ethereum, Solana, and 30+ EVM chains (Beta: currently limited to Ethereum and Base with a limit of 1 address)
 tags: ["📚 Portfolio APIs"]
 x-readme:
   samples-languages:

data/v1.yaml

@@ -455,6 +455,11 @@ components:
             Array of address and networks pairs (limit 3 pairs, max 20 networks each). Networks should match network enums.
           items:
             $ref: "#/components/schemas/AddressItemWith20Maximum"
+        includeNativeTokens:
+          type: boolean
+          description: Whether to include each chain's native token in the response (e.g. ETH on Ethereum). The native token will have a null contract address.
+          example: true
+          default: true
       required:
         - addresses
 
@@ -477,6 +482,11 @@ components:
           description: 'Boolean - if set to `true`, returns token prices. Setting this to false will reduce payload size and may result in a faster API call. Defaults to `true`.'
           type: boolean
           default: true
+        includeNativeTokens:
+          type: boolean
+          description: Whether to include each chain's native token in the response (e.g. ETH on Ethereum). The native token will have a null contract address.
+          example: true
+          default: true
       required:
         - addresses
 

prices/prices.yaml

@@ -355,6 +355,11 @@ components:
               enum: [ "5m", "1h", "1d" ]
               default: "1d"
               example: "1d"
+            withMarketData:
+              type: boolean
+              description: Whether to include market cap and volume for each token
+              example: true
+              default: false
         - required: ["network", "address", "startTime", "endTime"]
           properties:
             network:
@@ -396,6 +401,11 @@ components:
               enum: [ "5m", "1h", "1d" ]
               default: "1d"
               example: "1d"
+            withMarketData:
+              type: boolean
+              description: Whether to include market cap and volume for each token
+              example: true
+              default: false
 
     HistoricalPricesResponse:
       type: object
@@ -461,6 +471,14 @@ components:
           format: date-time
           description: Timestamp of the price data point.
           example: "2024-01-01T00:00:00Z"
+        marketCap:
+          type: string
+          description: Total market capitalization at the timestamp
+          example: "274292310008.21802"
+        totalVolume:
+          type: string
+          description: Volume traded during the defined interval
+          example: "6715146404.608721"
       required:
         - value
         - timestamp