# Reservoir MCP

> Reservoir (NFT Liquidity API) gives your AI agent real-time access to NFT market data across multiple major marketplaces. It aggregates active bids, asks, token metadata, and collection stats from platforms like OpenSea, LooksRare, and X2Y2 into a single stream. You can use this server to compare prices instantly, track floor prices for specific collections, or generate the transaction details needed to buy or sell an NFT directly via your client.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** nft, web3, ethereum, liquidity-aggregator, crypto-trading

## Description

**Reservoir NFT Liquidity API** gives your AI agent direct, real-time access to NFT market data across major marketplaces like OpenSea, LooksRare, and X2Y2. It aggregates bids and asks, token metadata, and collection stats into a single stream for actioning trades or analysis. You connect this server, and your agent gets the tools it needs to operate on live market liquidity.

When you're checking cross-market listings, you can pull every active sell listing (asks) across supported platforms using `list_asks`, and retrieve all currently active buy offers (bids) for entire collections or specific tokens via `list_bids`. This means your agent doesn't have to check multiple sites; it gets both sides of the ledger in one query. You can also use `list_tokens` to get a list of assets owned by an address, letting you filter those results based on criteria like rarity or contract type.

For deep market analysis, `get_collection` pulls real-time stats for any given NFT collection. That includes the floor price, total volume traded, and comprehensive metadata for the whole set. If your agent needs to dive into a single asset, `get_token` retrieves detailed information on that specific token, including its rarity score and history. To find new opportunities or assets, you can use `search_collections`, which lets your agent look up collections either by name or using their contract address. You'll always have the ability to list tokens held by an owner with filters applied, giving you a clear picture of an entire portfolio.

When it comes time to execute trades, the API provides the transaction mechanism. If your agent needs to buy an NFT, `execute_buy` generates the exact transaction payload required for that purchase. Conversely, if there's a pending offer—a bid waiting to be accepted—your agent can use `execute_sell` to create the necessary transaction payload to fill that bid and complete the sale.

## Tools

### execute_buy
Generates the required transaction payload needed to buy an NFT.

### execute_sell
Creates a transaction payload to accept a pending offer (fill a bid).

### get_collection
Fetches metadata and real-time stats for an entire NFT collection.

### get_token
Retrieves detailed information, including rarity, for a single specific token.

### list_asks
Pulls all active sell listings (asks) from supported marketplaces in one query.

### list_bids
Retrieves all active buy offers (bids) for tokens or entire collections.

### list_tokens
Gets a list of tokens based on various filters, like owner address or collection contract.

### search_collections
Searches for NFT collections using either the name or the contract address.

## Prompt Examples

**Prompt:** 
```
Search for the 'Azuki' collection and show me its floor price.
```

**Response:** 
```
I found the Azuki collection (Contract: 0xed5af... ). The current floor price is 5.42 ETH with a 24h volume of 120 ETH. Would you like to see the top active listings?
```

**Prompt:** 
```
List all tokens owned by address 0x123... sorted by rarity.
```

**Response:** 
```
Fetching tokens for that address... I found 12 NFTs. The rarest is 'Bored Ape #442' followed by 'Mutant Ape #1023'. Would you like the full metadata for the Bored Ape?
```

**Prompt:** 
```
Show me the active sell orders for token 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d:1.
```

**Response:** 
```
There are 3 active listings for this Bored Ape: 75 ETH on OpenSea, 74.9 ETH on LooksRare, and 76 ETH on X2Y2. I can generate a buy transaction for the cheapest one if you're ready.
```

## Capabilities

### Compare Cross-Market Listings
Pull active buy bids and sell asks from multiple marketplaces (e.g., checking both OpenSea and LooksRare) using `list_asks` and `list_bids`.

### Analyze Collection Metrics
Get real-time stats for any NFT collection, including its floor price, volume, and metadata, via the `get_collection` tool.

### Check Specific Token Details
Retrieve deep information—like rarity or history—for a single token using `get_token`.

### Discover Collections and Assets
Search for collections by name or contract address (`search_collections`), or list all tokens held by an owner with filters (`list_tokens`).

### Initiate NFT Trades
Generate the necessary transaction data to buy a specific NFT (`execute_buy`) or accept a pending offer (`execute_sell`).

## Use Cases

### Spotting Arbitrage Opportunities
A quant developer notices a collection's floor price is low on one site but high on another. They ask their agent to run `list_asks` across both platforms, identify the cheapest listing, and use `execute_buy` to prepare a cross-platform trade.

### Due Diligence on an Opponent's Wallet
An analyst wants to see everything a competitor owns. They run `list_tokens` against the opponent's address, filtered by contract type. This immediately surfaces all their holdings and allows them to use `get_collection` on any asset found.

### Automating Bid Monitoring
A trader needs to track a specific high-value token. They set up an agent that constantly runs `list_bids` for the target contract, alerting them when a bid reaches a certain threshold, so they can prepare to accept it with `execute_sell`.

### Quick Collection Vetting
A user finds a new collection by name. Instead of visiting the site, they ask their agent to run `search_collections`, then use `get_collection` on the resulting contract ID. They get the floor price and volume in seconds.

## Benefits

- Stop checking OpenSea, LooksRare, and X2Y2 separately. Using `list_asks` or `list_bids` pulls active listings from multiple sources at once, giving you a single view of market depth.
- Need to know if an NFT is rare? Call `get_token` with the contract address; it returns deep metadata and rarity scores instantly, saving manual lookup time.
- Don't just analyze—act. The server generates transaction data using `execute_buy`, letting your agent prepare a purchase without leaving the chat window.
- Research ownership patterns easily. Use `list_tokens` to pull all assets owned by a specific address and filter them, making it simple for due diligence.
- Get collection health metrics with `get_collection`. You immediately see the floor price and 24h volume, allowing you to vet an asset before writing any code.

## How It Works

The bottom line is: it lets your agent treat multiple, disparate NFT marketplaces as if they were one single API endpoint.

1. Subscribe to this server and input your Reservoir API Key.
2. Your AI client calls one of the 8 available tools (e.g., `get_collection` for metadata).
3. The server returns structured, aggregated market data or transaction payload that your agent can use immediately.

## Frequently Asked Questions

**How does the Reservoir (NFT Liquidity API) handle multiple marketplaces?**
The server aggregates data from major platforms like OpenSea and LooksRare. When you run `list_asks`, for example, it pulls all active listings from those sites into a single result set.

**Can I use the Reservoir (NFT Liquidity API) to buy an NFT?**
Yes. After analyzing the data with tools like `list_asks`, you can generate the necessary transaction details using the `execute_buy` tool, preparing your agent for a trade.

**What is the difference between `get_collection` and `search_collections`?**
`search_collections` finds the collection's contract ID based on a name or address. `get_collection`, however, uses that confirmed ID to pull real-time stats like floor price and volume.

**Is this API just for viewing data?**
No. While it excels at reading market data (`list_bids`), the server also provides write capabilities through `execute_sell` to generate transaction payloads for accepting offers.

**How do I authenticate when using list_asks?**
You include your API key in the request header. The server validates this credential before processing any query, guaranteeing that only authorized agents access live market data.

**What are the rate limits when calling get_token?**
The service enforces standard rate limits to protect against overuse. We advise your agent client to implement exponential backoff logic for stable and reliable data retrieval over time.

**How can I use list_tokens to filter by specific attributes?**
You pass the required criteria, like owner addresses or rarity scores, in the tool's parameters. This narrows your results set before it even hits the network, giving you highly targeted data.

**What does execute_buy return if the NFT is already sold?**
The tool returns a specific error code and an explanatory message detailing why the transaction failed. This allows your agent to handle exceptions gracefully without crashing the workflow.

**Can I check the floor price and volume for a specific NFT collection?**
Yes. Use the `get_collection` tool with the collection ID or contract address. It returns real-time stats including floor price, market cap, and volume metrics.

**How do I see all active buy offers for a particular NFT?**
Simply use the `list_bids` tool and provide the token identifier (contract:tokenId). The agent will list all active offers across supported marketplaces.

**Does this server allow me to actually buy an NFT through the AI?**
The `execute_buy` tool generates the necessary transaction data. You will still need to sign the transaction with your wallet (like MetaMask) to complete the purchase, ensuring full security.