# Reservoir MCP for AI Agents AI Agent Connect

> Reservoir (NFT Liquidity API) connects your agent to a massive pool of NFT listings and offers from marketplaces like OpenSea and X2Y2. It lets your AI pull real-time floor prices, search for specific collections, and even generate the data needed to buy or sell NFTs across multiple chains. It's the backbone for any agent that needs to navigate the decentralized NFT market without jumping between tabs.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_f8oRngSRqD3FZxykMhupyTGLHMx62tTE8zLE8WBy/ai-agent-connect
- **Tags:** nft, web3, ethereum, liquidity-aggregator, crypto-trading

## Description

Imagine you're trying to find the best price for a specific NFT across five different marketplaces. Usually, that's a manual slog of opening tabs, copying addresses, and comparing numbers. This Connector changes that by letting your AI agent do the heavy lifting. It pulls everything into one place including active listings, current bids, and deep metadata like rarity scores and collection volume. Instead of you digging through data, you just ask your agent to find the best deal or check a specific owner's holdings. It handles the messy details of the decentralized web so you can focus on the strategy. By connecting this to Vinkius, you get a unified way to interact with the Reservoir API, making it easy to feed real-time market movements into your workflow. You can generate the actual transaction data for buys or sells on the fly, turning your AI into a functional trading assistant. It's about moving from looking for data to acting on data without ever leaving your primary workspace. You get a direct line to aggregated liquidity that works across major chains.

## Tools

### execute_sell
Generates the transaction data to accept a bid. Use this when your agent needs to fill an existing offer.

### get_collection
Pulls metadata and live stats for an entire NFT collection. It gives you the big picture on floor prices and volume.

### get_token
Fetches every detail for a single NFT. This is perfect for checking rarity scores or specific traits.

### list_asks
Grabs all active listings from supported marketplaces at once. Use this to see what's currently for sale.

### list_bids
Pulls all active offers for specific tokens or collections. It helps you see what buyers are willing to pay.

### list_tokens
Returns a list of tokens based on your specific filters. You can use this to find items owned by certain addresses.

### search_collections
Finds collections using a name or a contract address. This is the first step for discovering new projects.

### execute_buy
Generates the transaction data needed to purchase an NFT. This lets your agent prepare a buy order for a specific listing.

## Prompt Examples

**Prompt:** 
```
Find the cheapest listing for a 'Pudgy Penguins' NFT across all marketplaces.
```

**Response:** 
```
I've scanned the major marketplaces. Here are the best active listings for Pudgy Penguins:

| Marketplace | Price | Link |
| :--- | :--- | :--- |
| **X2Y2** | **1.2 ETH** | [Link]
| **OpenSea** | 1.35 ETH | [Link]
| **LooksRare** | 1.42 ETH | [Link]

The best deal is currently on X2Y2. Would you like me to generate the buy transaction for that listing?
```

**Prompt:** 
```
What's the current floor price and 24h volume for the Azuki collection?
```

**Response:** 
```
### Azuki Collection Stats
- **Floor Price:** 5.42 ETH
- **24h Volume:** 120 ETH
- **Active Listings:** 48

The floor price has remained stable over the last 24 hours with steady volume. Would you like to see the top 5 listings?
```

**Prompt:** 
```
List all NFTs owned by 0x123... and tell me which one is the rarest.
```

**Response:** 
```
I'm pulling the holdings for that address now...

I found 12 NFTs. Here are the top 3 by rarity:
1. **Bored Ape #442** (High Rarity)
2. **Mutant Ape #1023** (Medium Rarity)
3. **CryptoPunk #7721** (High Rarity)

Would you like to see the full metadata for the Bored Ape?
```

## Capabilities

### Pull active listings from multiple marketplaces
Get a unified view of what's for sale on OpenSea, X2Y2, and other major platforms in one go.

### Retrieve real-time floor prices
Get up to the minute pricing and volume data for any NFT collection.

### Find specific collections
Search for projects by name or contract address to get instant data.

### Generate transaction data for purchases
Have your agent prepare the data needed to buy an NFT from a specific listing.

### Generate transaction data for sales
Prepare the data to accept an existing offer or fill a bid on a token.

### Search for tokens by wallet
Filter and list NFTs owned by specific addresses to track movements.

### Get detailed token metadata
Pull rarity scores and specific trait information for individual assets.

## Use Cases

### Arbitrage Hunting
A trader asks their agent to find the cheapest listing for a specific Bored Ape across three different marketplaces.

### Portfolio Auditing
An analyst wants to see every NFT held by a specific whale address sorted by rarity.

### Market Research
A developer needs to pull 24-hour volume and floor price data for a list of 20 different collections.

### Quick Selling
A user wants to see all current bids for their NFT and have the agent prepare a sell transaction for the highest one.

## Benefits

- Stop manually checking multiple tabs because list_asks pulls data from OpenSea, X2Y2, and others into one view.
- Get instant price alerts by using get_collection to monitor floor price movements and volume spikes.
- Automate your research with list_tokens to find specific assets owned by high-value wallets.
- Speed up your trading with execute_buy and execute_sell to generate transaction data without manual copying.
- Access deep project data using get_token to see rarity scores and metadata instantly.
- Simplify your discovery process by using search_collections to find projects by name or contract.

## How It Works

The bottom line is you get a direct line to aggregated NFT liquidity for your AI agent.

1. Subscribe to the Connector on Vinkius and get your Reservoir API key.
2. Add the API key to your preferred AI client settings.
3. Ask your agent to compare prices, find collections, or prepare trades.

## Frequently Asked Questions

**Can Reservoir (NFT Liquidity API) show me prices from multiple marketplaces?**
Yes, it pulls active listings from OpenSea, X2Y2, and others in one go. You don't have to check each site individually to find the best price.

**How does Reservoir (NFT Liquidity API) help with NFT trading?**
It generates the transaction data for buying or selling. Your agent can prepare the trade for you based on the best available offer, saving you from manual data entry.

**Can I use Reservoir (NFT Liquidity API) to find specific NFT collections?**
You can search by name or contract address. It finds the project and pulls the latest stats like floor price and volume instantly.

**Does Reservoir (NFT Liquidity API) provide metadata like rarity?**
Yes, it pulls detailed token info. Your agent can look up specific traits and rarity scores for any individual NFT in a collection.

**Is Reservoir (NFT Liquidity API) good for market research?**
It's great for pulling real-time stats. You can get volume data and collection-level stats for your reports without any manual scraping.

**Can my agent find NFTs owned by a specific wallet?**
Yes, it can list tokens based on owner filters. This helps you track whale movements or audit specific addresses quickly.

**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.