# Mflo Documentation
> Mflo is the data kernel for AI agents — a pay-per-query dataset marketplace built on the x402 HTTP standard and EIP-3009 meta-transactions. It provides instant, structured data access for AI agents, bots, and LLMs without requiring API keys or subscriptions.
Key features:
- x402 Payment Required HTTP responses for micro-payments
- Model Context Protocol (MCP) integration for AI agents
- EIP-3009 meta-transactions for gasless payments
- Wallet-based authentication (no API keys required)
- Pay-per-query pricing model with stablecoins
- Structured datasets across multiple categories
The platform consists of:
- x402_DMP (Dataset Marketplace) - Web UI for browsing datasets
- x402_API - Resource server handling payments and data serving
- Smart Contracts - EIP-3009 compatible mUSDC on Monad Network
- MCP Server - Model Context Protocol integration for AI agents
## Overview
- [FAQs](pages/overview/faqs.mdx)
- [Getting started](pages/overview/getting-started.mdx)
- [What is Mflo?](pages/overview/index.mdx)
### FAQs
# Frequently Asked Questions
## General Questions
### What is Mflo?
Mflo is a pay-per-query dataset marketplace built on the x402 HTTP standard and EIP-3009 meta-transactions. It enables AI agents to access structured data without API keys or subscriptions.
### How is this different from traditional APIs?
Traditional APIs require API keys, monthly subscriptions, and complex authentication. Mflo uses wallet-based authentication and micro-payments — you only pay for what you query.
## Technical Questions
### What wallets are supported?
Currently, MetaMask is supported for the web interface. The MCP server supports any wallet that can provide a private key.
### What tokens are accepted?
The demo uses mUSDC, a custom ERC20 token with 6 decimals. In production, this could be USDT, USDC or other stablecoins.
### How much do queries cost?
Dataset price:
- 0.50 mUSDC
### Can I use this in production?
The current implementation is a proof-of-concept for demonstration purposes. The smart contracts include warnings about production use and recommend audited alternatives.
## Setup Questions
### How do I get test tokens?
1. **Visit [Faucet](https://mflo.ai/faucet)**
2. **Connect your wallet**
3. **Add the Monad Testnet Network and Token** to your wallet
4. **Mint mUSDC (Testnet Stable Token)** for testing transactions
### Can I run this without the web interface?
Yes! The MCP server allows AI agents to access datasets directly without the web UI.
## MCP Integration
### What is MCP?
Model Context Protocol (MCP) is a standard that allows AI agents to access external tools and data sources securely.
### Which AI agents support MCP?
- VS Code with Cline extension
- Cursor IDE (built-in)
- Claude Desktop
- Custom agent frameworks
### Do I need to clone repositories?
No! The MCP server installs via `npx @mfloai/x402-mcp@demo` — no repository cloning required.
## Payment Questions
### Do users pay gas fees?
No! EIP-3009 meta-transactions allow the facilitator (server) to pay gas fees while users only sign messages.
### What happens if a payment fails?
Common failures include:
- Insufficient token balance
- Expired authorization (time bounds)
- Already-used nonce (replay protection)
- Invalid signature
### Can I get refunds?
Payments are final once processed on-chain. However, failed payments are not executed, so no tokens are transferred.
### How are payments verified?
The x402_API server verifies EIP-712 signatures and executes the `transferWithAuthorization` function on the smart contract.
## Security Questions
### Is my private key safe?
Private keys are only used locally by the MCP server process. Use dedicated keys with minimal permissions and rotate them regularly.
### How are replay attacks prevented?
Each payment authorization includes a unique nonce. Once used, the nonce cannot be reused, preventing replay attacks.
### What about time-based attacks?
Authorizations include `validAfter` and `validBefore` timestamps, creating time-bound validity windows.
## Troubleshooting
### Wallet not connecting?
- Ensure Wallet is installed and unlocked
- Check that you're on the correct network (Monad Testnet)
- Try refreshing the page or restarting the browser
### Payment signatures failing?
- Verify your wallet has sufficient mUSDC balance
- Check that the contract address is correct in your environment
- Ensure you're on the right network
### MCP server not starting?
- Verify Node.js ≥ 20 is installed
- Check that your `PRIVATE_KEY` is properly formatted (starts with `0x`)
- Try running the server manually first: `npx -y @mfloai/x402-mcp@demo`
### 402 errors in production?
- Ensure the x402_API server is running and accessible
- Verify payment requirements are being returned correctly
- Check server logs for payment verification errors
## Still Have Questions?
**Ask us on X (Twitter)** - Follow [@mfloai](https://twitter.com/mfloai) for updates and support.
### Getting started
# Getting Started
Welcome to Mflo! This guide will help you start accessing datasets through our x402 payment system. Choose the method that best fits your needs:
## Quick Access to Dataset
The easiest way to try Mflo is through our web interface using your crypto wallet - no complicated MCP setup required.
### What You'll Need
- A crypto wallet like **MetaMask** or any EVM-compatible wallet
- Some tokens for dataset payments (small amounts needed for most queries)
### Step-by-Step Instructions
1. **Visit the Mflo Website**
- Navigate to [Mflo.ai](https://mflo.ai) in your browser
- Browse available datasets without needing to sign in
2. **Connect Your Wallet**
- Click "Connect Wallet" when you're ready to access paid data
- Choose your wallet (MetaMask or any EVM-compatible wallet)
- Approve the connection in your wallet
3. **Access Dataset**
- Find a dataset you want to query
- Click "Query" or "Access Data"
- Your wallet will prompt you to sign the x402 payment
- Approve the transaction to access the data
4. **View Your Data**
- Once payment is confirmed, the dataset will load
- Data is delivered instantly through the x402 standard
**Note**: This method requires tokens for payments, but it's the quickest way to explore Mflo's capabilities with just a wallet connection.
## For Developers & AI Agents: MCP Client Access
Advanced users can also integrate Mflo into AI agents and development workflows using the **Model Context Protocol (MCP)**.
With MCP integration, your AI agents running inside IDEs or frameworks (MCP clients) can connect to the **x402 MCP Server** and access datasets directly — with payments handled automatically in the background.
👉 See [MCP Integration](/agents/mcp-integration) for setup instructions
👉 See [MCP Clients](/agents/mcp-clients) for details on supported environments
### Benefits of MCP Integration
- **Seamless AI workflows**: Your agents can access live data without manual intervention
- **Automatic payments**: No need to manually approve each transaction
- **Real-time data**: Get the latest information directly in your AI conversations
- **Developer-friendly**: Integrate into any MCP-compatible system
## What's Next?
Once you're set up with either method:
- **Explore datasets**: Browse our [available datasets](/datasets)
- **Learn about payments**: Understand [x402 payment concepts](/x402/concepts)
- **Advanced integrations**: Check out [MCP integration](/agents/mcp-integration) for custom setups
- **Get support**: Visit our [FAQ section](/overview/faqs) for common questions
## For AI Developers
### 🤖 **Integrate Mflo Knowledge into Your AI**
Want to give your AI agents comprehensive knowledge about Mflo? Download our LLM.txt file:
**[📥 llm.txt](/llm.txt)** — Complete documentation in AI-friendly format
Perfect for:
- Training custom AI agents about Mflo
- Providing context to LLMs for accurate responses
- Building AI-powered integrations with comprehensive knowledge
- Reducing hallucination with up-to-date documentation
Simply download and include in your AI system's context or training data.
## Need Help?
- **Quick questions**: Check our [FAQ section](/overview/faqs)
- **Technical issues**: Review our troubleshooting guides in each integration section
- **Custom integrations**: Contact our team for enterprise solutions
Start with the method that matches your technical comfort level - you can always upgrade to MCP integration later for more advanced use cases!
### What is Mflo?
# What is Mflo?
Mflo is the data kernel for AI agents — a pay-per-query dataset marketplace built on the x402 HTTP standard and EIP-3009 meta-transactions. It provides instant, structured data access for AI agents, bots, and LLMs without requiring API keys or subscriptions.
Powered by the Model Context Protocol (MCP) and x402, Mflo enables on-demand access across any dataset. MCP ensures seamless interoperability with AI agents and LLM ecosystems, while x402 standardizes payments and transport. Together, they make Mflo the foundation for universally accessible data in the age of intelligent agents.
## Core Concept
Traditional data APIs require:
- 🔑 **API Keys** - Complex authentication setup
- 💳 **Subscriptions** - Monthly commitments regardless of usage
- 🏗️ **Integration overhead** - Custom SDKs and rate limiting
Mflo uses **x402 Payment Required** HTTP responses to enable:
- ⚡ **Instant access** - Pay only for what you query
- 🤖 **Agent-native** - MCP (Model Context Protocol) integration
- 🔐 **Wallet-based auth** - Wallet signing, no API keys
- 💰 **Micro-payments** - Pay per dataset query with stablecoins
## How It Works
1. **AI agent requests data** → x402_API server returns `402 Payment Required`
2. **Payment prompt** → User signs EIP-712 message via Wallet like Metamask
3. **Payment settlement** → EIP-3009 meta-transaction processes payment
4. **Data delivery** → Protected dataset served instantly
## Architecture
The Mflo ecosystem consists of:
- **x402_DMP** (Dataset Marketplace) - Web UI for browsing and testing datasets
- **x402_API** - Resource server handling payment verification and data serving
- **Smart Contracts** - EIP-3009 compatible mUSDC testnet stablecoin on Monad Network for payments
- **MCP Server** - Model Context Protocol integration for AI agents
## Key Features
### 🔗 **MCP-Native Integration**
Built-in Model Context Protocol server allows AI agents to query datasets directly through natural language.
### 💸 **x402 Pay-Per-Query**
HTTP 402 "Payment Required" standard enables micro-payments for individual data requests.
### 🏦 **EIP-3009 Meta-Transactions**
Off-chain signed payments settled on-chain without gas fees for users.
### 📊 **Structured Data**
All datasets provide schema definitions and sample data for easy agent integration.
### 🚀 **Instant Access**
No registration, no API keys — just connect your wallet and start querying.
## Use Cases
- **AI Agent Data Access** — Real-time market data, weather, news feeds
- **Research & Analysis** — Historical datasets for training and backtesting
- **Micro-payment Testing** — Demonstrating x402 and EIP-3009 standards
- **Decentralized Data Markets** — Proof-of-concept for trustless data exchange
## For AI Developers
### 📄 **LLM.txt Documentation**
Access our complete documentation in LLM-friendly format:
**[📥 Download llm.txt](/llm.txt)** — Complete Mflo documentation optimized for AI systems
This file contains all our documentation in the [LLM.txt standard format](https://llmstxt.org/), making it easy to:
- Feed into your AI agents and LLMs
- Get accurate, up-to-date information about Mflo
- Integrate Mflo knowledge into your AI applications
- Reduce hallucination with comprehensive context
**File Stats:** ~48KB • 1,266 lines • 6,713 words • Auto-updated
## x402 Payment
- [Concepts](pages/x402/concepts.mdx)
- [Supported Wallets](pages/x402/supported-wallets.mdx)
- [Testing x402](pages/x402/testing-x402.mdx)
- [Testnet Tokens](pages/x402/testnet-tokens.mdx)
### Concepts
# x402 Payment Concepts
The Mflo platform implements the **x402 HTTP Payment Required** standard combined with **EIP-3009 meta-transactions** to enable seamless micro-payments for data access.
## Glossary
- **[x402](https://x402.org/)** is an HTTP standard based on the 402 "Payment Required" status code.
The 402 code was reserved in the HTTP specification but not defined.
x402 uses it to create a clear protocol for pay-per-request web services:
when you request a protected resource, the server shows the payment required, and after payment, you get access to the data or service.
- **[EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)** defines a method for **off-chain authorization of ERC-20 token transfers**.
Instead of sending on-chain approval transactions, users sign messages that authorize token transfers. These signed messages can be executed by third parties, allowing seamless transfers while eliminating gas fees for the end user.
### How It Works
1. **Client makes request** to protected resource
2. **Server responds with 402** including payment requirements
3. **Client processes payment** using the specified method
4. **Client retries request** with payment proof
5. **Server validates payment** and serves the resource
### Payment Requirements Format
When a resource requires payment, the server responds with:
```json
{
"error": "Payment required",
"paymentRequired": {
"paymentRequirements": [
{
"scheme": "exact",
"network": "localhost",
"payTo": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
"maxAmountRequired": "50000000"
}
]
}
}
```
## EIP-3009 Meta-Transactions
EIP-3009 enables **off-chain authorization** of token transfers that can be executed by third parties.
### Key Benefits
- **No gas fees for users** — Facilitator pays transaction costs
- **Offline signing** — Users sign messages, not transactions
- **Replay protection** — Nonces prevent duplicate authorizations
- **Time bounds** — Authorizations can have validity windows
### Authorization Flow
```mermaid
sequenceDiagram
participant User
participant Web Client
participant x402 API
participant Blockchain
User->>Web Client: Request dataset
Web Client->>x402 API: GET /api/datasets/id
x402 API->>Web Client: 402 Payment Required
Web Client->>User: Request payment signature
User->>Web Client: Sign EIP-712 message
Web Client->>x402 API: POST with X-Payment header
x402 API->>Blockchain: Execute transferWithAuthorization
Blockchain->>x402 API: Transfer confirmed
x402 API->>Web Client: Resource data
```
## Security Considerations
### Nonce Management
- Each authorization uses a unique nonce
- Prevents replay attacks
- Tracked on-chain in `authorizationState` mapping
### Time Bounds
- `validAfter` - Authorization not valid before this timestamp
- `validBefore` - Authorization expires after this timestamp
- Prevents indefinite authorization reuse
### Signature Verification
- EIP-712 structured data signing
- Domain separation prevents cross-contract attacks
- Cryptographic proof of user intent
## Error Handling
Common payment errors and their meanings:
- **"not yet valid"** — Current time < validAfter
- **"authorization expired"** — Current time > validBefore
- **"authorization used"** — Nonce already consumed
- **"invalid signature"** — Signature verification failed
- **"insufficient funds"** — User balance too low
### Supported Wallets
# Supported Wallets
## Summary
The x402 payment system supports any cryptocurrency wallet that implements standard signing methods, particularly EIP-712 structured data signing. This includes the vast majority of EVM-compatible wallets, making x402 accessible to users across the Ethereum ecosystem and compatible networks.
## General Requirements
Any wallet that supports the following standards is compatible with x402:
- **EIP-712 Structured Data Signing** — Required for creating payment authorizations
- **EVM Compatibility** — Must work with Ethereum and EVM-compatible networks
- **Standard JSON-RPC Methods** — Support for `eth_signTypedData_v4` or similar signing methods
This broad compatibility means that most modern cryptocurrency wallets work seamlessly with the x402 payment protocol without requiring special integrations or modifications.
## Supported Wallet Categories
| Wallet Category | Description |
|-----------------|-------------|
| **EVM-Compatible Wallets** | Any wallet supporting EIP-712 signing on Ethereum and EVM networks. Includes popular options like MetaMask, Trust Wallet, Coinbase Wallet, Rainbow, and many others. These wallets provide the standard signing interface required for x402 payments. |
| **CDP Wallet** | Coinbase Developer Platform wallet, specifically recommended in the documentation for its robust developer tooling and seamless integration with x402 payment flows. Offers excellent support for structured data signing and meta-transactions. |
| **AgentKit** | Developer-focused wallet solution designed for AI agent integrations. Provides programmatic access to signing capabilities, making it ideal for automated systems and AI agents that need to execute x402 payments without manual user intervention. |
## Key Features
### **Universal Compatibility**
The x402 standard leverages existing wallet infrastructure, meaning no special wallet modifications or plugins are required. If your wallet can sign EIP-712 messages, it can process x402 payments.
### **No Additional Setup**
Users don't need to install special extensions or configure additional settings. The payment flow works through standard wallet signing interfaces that users are already familiar with.
## Developer Integration
### **Web Applications**
```javascript
// Works with any EIP-712 compatible wallet
const signature = await window.ethereum.request({
method: 'eth_signTypedData_v4',
params: [userAddress, typedData]
});
```
### **Mobile Applications**
Mobile wallets that support WalletConnect or similar protocols can integrate with x402-enabled applications through standard connection methods.
### **Programmatic Access**
For AI agents and automated systems, wallets like AgentKit provide programmatic signing capabilities:
```javascript
// Example with AgentKit or similar programmatic wallet
const wallet = new ProgrammaticWallet(privateKey);
const signature = await wallet.signTypedData(domain, types, message);
```
## Testing and Development
### **Local Development**
For testing x402 integrations, any wallet that can connect to local networks (like Hardhat's localhost:8545) will work. MetaMask is commonly used for local development due to its easy network configuration.
### **Testnet Support**
All supported wallets can be configured to work with testnets, allowing developers to test x402 payment flows without using real funds.
## Security Considerations
### **Private Key Management**
- Use dedicated wallets for x402 payments when possible
- Implement spending limits through wallet settings
- Regularly rotate keys for programmatic wallets
- Monitor transaction history for unusual activity
### **Network Security**
- Verify you're connected to the correct network before signing
- Double-check payment amounts and recipients
- Use hardware wallets for high-value operations when supported
## Getting Started
1. **Choose any EVM-compatible wallet** from the categories above
2. **Configure for your target network** (mainnet, testnet, or local)
3. **Ensure sufficient token balance** for payments
4. **Connect to x402-enabled applications** using standard wallet connection methods
The x402 protocol's wallet-agnostic design ensures that users can leverage their existing wallet preferences while accessing pay-per-query datasets and services.
### Testing x402
# Testing x402
## Testing x402 Payments
### Prerequisites
Before testing x402 payments, ensure you have:
- **Monad Testnet** added to your wallet
- **MON tokens** for gas fees
- **mUSDC tokens** for payment testing
- **Wallet connected** to Mflo webpage
### Basic Testing Flow
1. **Connect your wallet** to Mflo webpage
2. **Select a dataset** or service requiring payment
3. **Approve the x402 payment** in your wallet
4. **Sign the payment authorization** using EIP-712
5. **Verify the transaction** on the [Monad block explorer](https://testnet.monadexplorer.com/)
6. **Check the data** to ensure you received the correct dataset or service response
### Example Payment Transaction
```javascript
// Example x402 payment structure
const paymentData = {
recipient: "0x...", // Service provider address
amount: "1000000", // 1 mUSDC (6 decimals)
token: "0x72c0839d3CAcb2FB77569c221EDB3A547C6a242d", // mUSDC contract
nonce: 12345,
deadline: 1234567890
};
```
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| **Network not found** | Manually add Monad Testnet using the configuration above |
| **No MON for gas** | Request MON tokens from the faucet |
| **mUSDC not showing** | Import the token contract manually in your wallet |
| **Transaction failing** | Ensure sufficient MON balance for gas fees |
| **Payment not processing** | Verify mUSDC balance and allowance |
### Getting Help
- **Community Support**: Follow [@Mflo](https://x.com/MfloAI) X account
- **Block Explorer**: Use `https://testnet.monadexplorer.com/` to verify transactions
## Security Notes
- **Testnet only**: These tokens have no real value
- **Private keys**: Keep your testnet private keys secure but separate from mainnet
- **Reset wallets**: Consider using dedicated testnet wallets
- **Regular updates**: Network parameters may change during testnet phases
### Testnet Tokens
# Testnet Tokens
## Overview
Testnet tokens allow developers and users to test Mflo functionality without using real cryptocurrency. These tokens are specifically designed for testing and development purposes.
## Monad Testnet
The primary testnet for Mflo development and testing is the [Monad](https://monad.xyz/) Testnet. Monad is a high-performance EVM-compatible blockchain optimized for decentralized applications.
### Network Configuration
| Parameter | Value |
|-----------|-------|
| **Network Name** | Monad Testnet |
| **Default RPC URL** | `https://testnet-rpc.monad.xyz/` |
| **Chain ID** | `10143` |
| **Currency Symbol** | MON |
| **Block Explorer URL** | `https://testnet.monadexplorer.com/` |
### Adding Monad Testnet to Your Wallet
**Easy Method:** Click the "Add Monad Testnet to Wallet" button to automatically configure your wallet.
**Manual Method:** If the button doesn't work or you prefer manual setup:
1. **Open your wallet** and navigate to network settings
2. **Select "Add Network"** or "Custom RPC"
3. **Enter the network details**:
- Network Name: `Monad Testnet`
- RPC URL: `https://testnet-rpc.monad.xyz/`
- Chain ID: `10143`
- Currency Symbol: `MON`
- Block Explorer URL: `https://testnet.monadexplorer.com/`
4. **Save** and switch to the Monad Testnet
## Test Stable Token
### mUSDC (Mflo USDC)
mUSDC is a test stablecoin designed for testing stable payment functionality on Monad Testnet by Mflo. It mimics the behavior of USD stablecoins but has no real-world value, making it perfect for development and testing x402 payment flows without financial risk.
**Token Details:**
```
Token Contract: 0x72c0839d3CAcb2FB77569c221EDB3A547C6a242d
Token Symbol: mUSDC
Decimals: 6
```
### Adding mUSDC to Your Wallet
**Easy Method:**
- Click the "Add mUSDC to Wallet" button to automatically add the token to your wallet
**Manual Method:** If the buttons don't work or you prefer manual setup:
1. **Switch to Monad Testnet** in your wallet
2. **Import custom token** using the contract address
3. **Enter token details**:
- Contract Address: `0x72c0839d3CAcb2FB77569c221EDB3A547C6a242d`
- Token Symbol: `mUSDC`
- Decimals: `6`
4. **Add token** to see your mUSDC balance
## Getting Testnet Tokens
There are two ways to get testnet MON tokens:
### Option 1: Mflo Faucet
Use the Mflo faucet to get both MON and mUSDC tokens in one place:
- **MON tokens**: For gas fees on Monad Testnet
- **mUSDC tokens**: For testing x402 payments
Simply connect your wallet to the Mflo faucet and request tokens.
### Option 2: Monad Official Faucet
Visit the [Monad Faucet](https://faucet.monad.xyz/) and follow their steps to get MON tokens for gas fees. Note that this option only provides MON tokens - you'll still need to get mUSDC separately through the Mflo faucet or other methods.
## Build for Agents
- [MCP Clients](pages/agents/mcp-clients.mdx)
- [MCP integration](pages/agents/mcp-integration.mdx)
### MCP Clients
# MCP Client Setup
This page shows you how to set up different AI tools to work with the Mflo x402 MCP server.
> **Prerequisites**: First get your MCP server configuration from [x402 MCP Server Integration](/agents/mcp-integration).
## Supported Clients
Choose your AI tool:
- [Visual Studio Code (with Cline)](#visual-studio-code-with-cline)
- [Cursor IDE](#cursor-ide)
- [Claude Desktop](#claude-desktop)
## Setup Instructions
### Visual Studio Code (with Cline)
1. **Install Cline extension**
- Go to Extensions in VS Code
- Search for "Cline" and install it
2. **Add MCP server**
- Open Settings → search "MCP Servers"
- Paste your JSON configuration from the integration page
- Set your `PRIVATE_KEY`
3. **Restart VS Code**
- Command Palette → "Developer: Reload Window"
4. **Test it**
- Open Cline panel
- Ask: "list datasets"
- The AI will connect to the MCP server and show results
### Cursor IDE
1. **Open Cursor settings**
- Go to Cursor → Settings
- Search for "MCP"
2. **Add MCP server**
- Paste your JSON configuration
- Set your `PRIVATE_KEY`
3. **Restart Cursor**
4. **Test it**
- In Chat/Composer, ask: "list datasets"
- Cursor will connect and return data
### Claude Desktop
1. **Find config file**
- Location: `~/Library/Application Support/Claude/claude_desktop_config.json`
2. **Add configuration**
```json
{
"mcpServers": {
"@mfloai/x402-mcp": {
"command": "npx",
"args": [
"-y",
"-p",
"@mfloai/x402-mcp@demo",
"x402-mcp"
],
"env": {
"PRIVATE_KEY": "EVM_PRIVATE_KEY"
}
}
}
}
```
3. **Restart Claude Desktop**
4. **Test it**
- Ask Claude: "list available datasets"
- Claude will use the MCP server automatically
## What You Can Do
Once set up, your AI can:
- **Browse datasets**: "What datasets are available?"
- **Get data details**: "Show me details for the Bitcoin dataset"
- **Query data**: "Get me the latest Bitcoin price"
- **Download datasets**: "Download the crypto trading data"
The AI handles all payments automatically using your private key.
## Additional Integrations
### Continue.dev (VS Code Extension)
Continue.dev provides AI coding assistance with MCP tool support.
**Setup**:
1. Install Continue extension in VS Code
2. Configure MCP server in Continue settings
3. Enable tool usage in your Continue configuration
**Use Cases**:
- Data-driven code generation
- Real-time market data for trading algorithms
- Research assistance with live datasets
### Cody by Sourcegraph
Cody can integrate with MCP servers for enhanced context.
**Integration**:
- Configure MCP server in Cody settings
- Use datasets for code analysis and suggestions
- Access real-time data during development
### Custom Agent Frameworks
#### LangChain Integration
```python
from langchain.tools import Tool
from mcp_client import MCPClient
# Connect to Mflo MCP server
mcp = MCPClient("npx @mfloai/x402-mcp@demo")
# Create LangChain tools
dataset_tool = Tool(
name="get_crypto_data",
description="Get cryptocurrency price data",
func=mcp.call_tool
)
```
#### AutoGen Integration
```python
from mcp_integration import MfloMCPTool
# Add Mflo tools to AutoGen AI agent
agent = autogen.AssistantAgent(
name="data_analyst",
tools=[MfloMCPTool()]
)
```
#### CrewAI Integration
```python
from crewai import Agent, Tool
from mflo_mcp import MfloDataTool
agent = Agent(
role='Data Analyst',
tools=[MfloDataTool()]
)
```
## Enterprise Integrations
### Jupyter Notebooks
Use the MCP server in data science workflows:
```python
# Call MCP server directly
result = subprocess.run([
"npx", "@mfloai/x402-mcp@demo",
"--tool", "get_dataset",
"--args", "{\"id\": \"crypto-prices\"}"
], capture_output=True, text=True)
data = json.loads(result.stdout)
```
### API Gateway Integration
Proxy MCP tools through your existing API infrastructure:
```javascript
// Express.js middleware
app.post('/api/mcp/:tool', async (req, res) => {
const { tool } = req.params;
const result = await mcpClient.callTool(tool, req.body);
res.json(result);
});
```
### Slack/Discord Bots
Integrate dataset access into chat platforms:
```javascript
// Discord.js bot with MCP
bot.on('messageCreate', async (message) => {
if (message.content.startsWith('!crypto')) {
const data = await mcpClient.callTool('get_crypto_data');
message.reply('Current BTC price: ' + data.price);
}
});
```
## Development Frameworks
### Next.js Applications
Server-side dataset fetching with MCP:
```javascript
// pages/api/data.js
const mcp = new MCPClient();
const data = await mcp.getDataset(req.query.id);
res.json(data);
}
```
### React Components
Client-side MCP integration:
```jsx
function DatasetViewer({ datasetId }) {
const { data, loading, error } = useMCP('get_dataset', { id: datasetId });
if (loading) return Loading...
;
return {`JSON.stringify(data, null, 2)`}
;
}
```
## Protocol Compatibility
### MCP Version Support
- **MCP 1.0**: Full compatibility
- **MCP 2.0**: Planned support
- **Legacy protocols**: Bridge adapters available
### Transport Methods
- **HTTP**: Standard REST API calls
- **WebSocket**: Real-time data streaming
- **gRPC**: High-performance integrations
- **SSE**: Server-sent events for live updates
## Authentication Patterns
### API Key Proxy
For clients that don't support private key signing:
```javascript
// Proxy server handles wallet operations
app.use('/mcp-proxy', (req, res, next) => {
req.headers['x-private-key'] = process.env.WALLET_PRIVATE_KEY;
next();
});
```
### Multi-tenant Support
Different private keys per client:
```json
{
"mcpServers": {
"mflo-client-a": {
"command": "npx",
"args": ["-y", "@mfloai/x402-mcp@demo"],
"env": {
"PRIVATE_KEY": "0xCLIENT_A_KEY"
}
},
"mflo-client-b": {
"command": "npx",
"args": ["-y", "@mfloai/x402-mcp@demo"],
"env": {
"PRIVATE_KEY": "0xCLIENT_B_KEY"
}
}
}
}
```
## Monitoring & Analytics
### Usage Tracking
Monitor MCP tool usage across clients:
```javascript
// Track tool calls
mcpClient.on('tool_call', (tool, args, result) => {
analytics.track('mcp_tool_used', {
tool,
client: req.headers['user-agent'],
success: !result.error
});
});
```
### Performance Metrics
- Tool call latency
- Payment processing time
- Error rates by client type
- Dataset popularity
## Security Considerations
### Private Key Management
- Use dedicated keys per client
- Implement key rotation policies
- Monitor for unusual spending patterns
- Set spending limits per key
### Network Security
- TLS encryption for all communications
- VPN requirements for enterprise deployments
- IP allowlisting for sensitive environments
### Audit Logging
- Log all tool calls and payments
- Track data access patterns
- Monitor for suspicious activity
- Compliance reporting capabilities
### MCP integration
# x402 MCP Server Integration
## Overview
The x402 MCP Server Integration enables AI agents running inside IDEs or frameworks (MCP clients) to seamlessly access datasets through the x402 MCP server.
This guide explains how to:
1. Install and configure the **x402 MCP Server**
2. Connect it to an **MCP Client** (e.g., VS Code with Cline, Cursor IDE)
3. Use the **AI Agent** to call MCP tools (e.g., `list_datasets`, `query_dataset`)
---
## Glossary
- **MCP Server**
A process that exposes tools and APIs to clients.
Here: the **x402 MCP Server**, which bridges AI requests to the x402 API and handles payments.
- **MCP Client**
The environment or IDE that launches and manages MCP servers.
Examples: VS Code with the Cline extension, Cursor IDE, Claude Desktop.
- **AI Agent**
The assistant running inside the MCP client.
It interprets user instructions and calls MCP server tools through the client.
---
## 1. What You Get
- **One-line install** via npx (no repo clone required)
- Your **AI agents** can access paid x402 endpoints through the **MCP server**
- Only a `PRIVATE_KEY` is required for setup
---
## 2. Prerequisites
- Node.js ≥ 18 and npm installed
```bash
node -v
npm -v
```
- An x402-compatible private key (hex format, `0x…`)
---
## 3. MCP Server Configuration
The MCP server is available as an npm package: [@mfloai/x402-mcp](https://www.npmjs.com/package/@mfloai/x402-mcp)
Paste the following JSON snippet into your MCP client's configuration (e.g., Cline or Cursor):
```json
{
"mcpServers": {
"@mfloai/x402-mcp": {
"command": "npx",
"args": [
"-y",
"-p",
"@mfloai/x402-mcp@demo",
"x402-mcp"
],
"env": {
"PRIVATE_KEY": "EVM_PRIVATE_KEY"
}
}
}
}
```
> **Note:** `API_BASE_URL` is optional. Include it only if your deployment requires a custom endpoint.
### Optional: Run once from terminal (sanity check)
```bash
PRIVATE_KEY=0xYOUR_PRIVATE_KEY \
npx -y @mfloai/x402-mcp@demo
```
If successful, the server will announce the available tools. Stop with `Ctrl+C`.
---
## 4. Next Steps
For detailed client setup instructions, see [MCP Client Setup](/agents/mcp-clients).
### 📄 **LLM.txt Documentation**
For AI developers who want to provide comprehensive Mflo knowledge to their AI systems:
**[📥 Download llm.txt](/llm.txt)** — Complete Mflo documentation in LLM-friendly format
This file contains all our documentation optimized for AI consumption, perfect for:
- Giving your AI agents complete knowledge about Mflo
- Training custom models with accurate Mflo information
- Providing context to LLMs for better responses
- Building AI applications with comprehensive Mflo understanding
---
## 5. Example Interactions
```
User: "What cryptocurrency datasets are available?"
AI Agent: [Calls list_datasets via MCP server]
AI Agent: "I found several crypto datasets including real-time prices, trading volumes, and historical data..."
User: "Get me the latest Bitcoin price data"
AI Agent: [Calls query_dataset via MCP server, x402 payment handled automatically]
AI Agent: "Here's the latest Bitcoin data: BTC/USDT at $68,123.45..."
```
---
## 6. Troubleshooting
| Issue | Solution |
|------|----------|
| **Command not found: npx** | Install Node.js ≥ 18 |
| **402 Payment Required** | Ensure your `PRIVATE_KEY` is valid and has sufficient funds/authorization |
| **Timeouts / no data** | Check network/proxy settings; report bugs or errors via the GitHub repository |
---
## 7. Security Notes
- The `PRIVATE_KEY` is only stored in the MCP server process spawned by your IDE.
- Prefer a dedicated key with minimal on-chain permissions, and rotate it periodically.
---
## 8. Version Pinning
- To pin a version, replace `@demo` with a semver range or exact version, e.g.:
- `@mfloai/x402-mcp@0.1.x`
- `@mfloai/x402-mcp@0.1.3`
---
## 9. How It Works (Summary)
1. **User** gives instructions to the **AI Agent**.
2. The **AI Agent** requests a tool via the **MCP Client**.
3. The **MCP Client** spawns the **MCP Server**.
4. The **MCP Server** calls the **x402 API**, handling payments automatically with `PRIVATE_KEY`.
5. **Results** are returned to the AI Agent, then presented to the user.
## Datasets
- [Available Datasets](pages/datasets/available-datasets.mdx)
- [API Schema](pages/datasets/schema.mdx)
### Available Datasets
# Available Datasets
The Mflo x402 MCP server provides access to a comprehensive data marketplace with datasets across multiple categories and formats. Use the [`list_datasets`](pages/datasets/schema.mdx:17) tool to discover available datasets with filtering and pagination.
## Data Categories
The marketplace currently offers datasets across the following categories:
### **FINANCIAL**
Financial markets, trading, investments
- Stock prices and market data
- Trading volumes and analytics
- Investment portfolios and performance metrics
- Financial indicators and ratios
### **BUSINESS**
Business metrics, company data
- Company financial statements
- Business performance indicators
- Market analysis and competitive intelligence
- Corporate governance data
## Future Updates
Additional dataset categories will be available in upcoming releases:
### **SOCIAL**
Social media, news, sentiment
- Social media posts and engagement metrics
- News articles and sentiment analysis
- Public opinion and trend data
- Community discussions and forums
### **WEATHER**
Weather data, climate information
- Current weather conditions
- Historical climate data
- Weather forecasts and predictions
- Environmental monitoring data
### **ECONOMIC**
Economic indicators, GDP, inflation
- GDP and economic growth metrics
- Inflation rates and price indices
- Employment and labor statistics
- Trade and commerce data
### **SCIENTIFIC**
Research data, academic datasets
- Research publications and citations
- Experimental data and results
- Academic performance metrics
- Scientific measurements and observations
### **GOVERNMENT**
Public sector data, regulations
- Government statistics and reports
- Regulatory filings and compliance data
- Public policy documents
- Census and demographic data
### **HEALTH**
Healthcare, medical data
- Medical research and clinical trials
- Health statistics and epidemiology
- Healthcare facility data
- Patient outcomes and treatment effectiveness
### **TRANSPORT**
Transportation, logistics data
- Traffic patterns and congestion data
- Public transportation schedules and usage
- Shipping and logistics information
- Vehicle registration and safety data
### **ENERGY**
Energy consumption, renewable data
- Energy production and consumption metrics
- Renewable energy generation data
- Grid performance and efficiency
- Carbon emissions and environmental impact
### **REAL_ESTATE**
Property, housing market data
- Property prices and market trends
- Real estate transactions and listings
- Housing market analytics
- Property valuations and assessments
### **EDUCATION**
Educational data, student metrics
- Student performance and achievement data
- Educational institution rankings
- Curriculum and course information
- Learning outcomes and assessments
### **ENTERTAINMENT**
Media, gaming, streaming data
- Entertainment industry metrics
- Gaming statistics and player behavior
- Streaming platform data and viewership
- Content performance and engagement
### **TECHNOLOGY**
Tech industry, software metrics
- Software development and deployment data
- Technology adoption and usage statistics
- IT infrastructure and performance metrics
- Innovation and patent data
### **OTHER**
Miscellaneous datasets
- Specialized and niche datasets
- Custom data collections
- Experimental and research datasets
- Community-contributed data
## Supported Data Formats
The marketplace currently supports the following data formats:
- **CSV**: Comma-separated values
- **JSON**: JavaScript Object Notation
### Future Format Support
Additional data formats will be supported in upcoming releases:
- **XML**: Extensible Markup Language
- **PARQUET**: Columnar storage format
- **AVRO**: Apache Avro format
- **PROTOBUF**: Protocol Buffers
- **EXCEL**: Microsoft Excel format
- **SQLITE**: SQLite database
- **POSTGRES**: PostgreSQL dump
- **MYSQL**: MySQL dump
- **STREAM**: Real-time streaming data
- **API**: REST API endpoint
- **GRAPHQL**: GraphQL endpoint
- **OTHER**: Other formats
## Dataset Discovery
Use the MCP server tools to discover and access datasets:
```javascript
// List all financial datasets
const datasets = await mcp.list_datasets({
category: "FINANCIAL",
limit: 10
});
// Get details of a specific dataset
const details = await mcp.get_dataset_details({
datasetId: "finance-stocks-2024"
});
```
## Example Dataset Structure
```json
{
"id": "finance-stocks-2024",
"name": "Stock Market Data 2024",
"description": "Comprehensive stock market data including prices, volumes, and analytics",
"category": "FINANCIAL",
"format": "CSV",
"price": 100,
"provider": "Financial Data Corp",
"size": 15728640,
"tags": ["stocks", "market-data", "2024", "financial"],
"lastUpdated": "2024-12-03T10:00:00Z",
"schema": {
"type": "text/csv",
"columns": [
{ "name": "symbol", "type": "string" },
{ "name": "price", "type": "number" },
{ "name": "volume", "type": "number" },
{ "name": "timestamp", "type": "string" }
]
}
}
### API Schema
# API Schema
The Mflo x402 marketplace provides access to various datasets through a standardized API. Each dataset includes schema definitions, pricing information, and sample data.
## API Endpoints
### Base URL
```
http://localhost:4000/api # Local development
```
### Authentication
All paid endpoints use x402 payment authentication. Free endpoints require no authentication.
## Dataset API Routes
### GET `/datasets`
**Free Access** - List all available datasets
```json
{
"data": {
"datasets": [
{
"id": "binance-crypto-prices",
"name": "Cryptocurrency Price Data",
"description": "Real-time cryptocurrency prices from Binance exchange",
"price": 50,
"provider": "Binance",
"type": "CSV",
"size": 1228,
"tags": ["cryptocurrency", "prices", "real-time", "binance"],
"lastUpdated": "2024-05-22T10:00:00Z"
}
]
}
}
```
### GET `/datasets/providers`
**Free Access** - Get all data providers
```json
{
"data": {
"providers": ["Binance", "CoinGecko", "Weather API", "Sample Data"]
}
}
```
### GET `/datasets/:id`
**Payment Required** - Get detailed dataset information
- **Cost**: 0.5 mUSDC (0.50 USD equivalent)
```json
{
"data": {
"dataset": {
"id": "binance-crypto-prices",
"name": "Cryptocurrency Price Data",
"description": "Real-time cryptocurrency prices from Binance exchange",
"price": 50,
"provider": "Binance",
"type": "CSV",
"size": 1228,
"tags": ["cryptocurrency", "prices", "real-time", "binance"],
"lastUpdated": "2024-05-22T10:00:00Z",
"schema": {
"type": "text/csv",
"columns": [
{ "name": "symbol", "type": "string" },
{ "name": "price", "type": "number" },
{ "name": "volume_24h", "type": "number" },
{ "name": "timestamp", "type": "string" }
]
}
}
}
}
```
### GET `/datasets/:id/preview`
**Free Access** - Get dataset preview/sample
```json
{
"data": {
"preview": "symbol,price,volume_24h,timestamp\nBTCUSDT,68123.45,34567.89,2024-05-22T10:00:00Z"
}
}
```
### POST `/datasets/:id`
**Payment Required** - Request dataset access
- **Cost**: 50 mUSDC per dataset
Returns authorization token for subsequent downloads.
### GET `/datasets/:id/download`
**Payment Required** - Download full dataset
- **Cost**: 50 mUSDC per download
- **Authorization**: Requires payment or valid auth token
## Payment Flow
### 1. Request Protected Resource
```bash
curl http://localhost:4000/api/datasets/binance-crypto-prices \
-H "Content-Type: application/json"
```
**Response (402 Payment Required)**:
```json
{
"error": "Payment required",
"paymentRequired": {
"paymentRequirements": [
{
"scheme": "exact",
"network": "localhost",
"payTo": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
"maxAmountRequired": "50000000"
}
]
}
}
```
### 2. Submit Payment
```bash
curl http://localhost:4000/api/datasets/binance-crypto-prices \
-X POST \
-H "Content-Type: application/json" \
-H "X-Payment: eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJsb2NhbGhvc3QiLCJwYXlsb2FkIjp7ImZyb20iOiIweDcwOTk3OTcwQzUxODEyZGMzQTAxMEM3ZDAxYjUwZTBkMTdkYzc5QzgiLCJ0byI6IjB4NzA5OTc5NzBDNTE4MTJkYzNBMDEwQzdkMDFiNTBlMGQxN2RjNzlDOCIsInZhbHVlIjoiNTAwMDAwMDAiLCJ2YWxpZEFmdGVyIjoiMCIsInZhbGlkQmVmb3JlIjoiMTcxNjM4NzYwMCIsIm5vbmNlIjoiMHgxMjM0NTY3ODkwYWJjZGVmIn0sInNpZ25hdHVyZSI6IjB4YWJjZGVmIn0="
```
**Response (200 Success)**:
```json
{
"data": {
"dataset": { /* dataset details */ },
"authorizationToken": "auth_token_for_downloads"
}
}
```
## Error Codes
| Code | Message | Description |
|------|---------|-------------|
| 200 | OK | Request successful |
| 402 | Payment Required | Payment needed for resource access |
| 404 | Not Found | Dataset ID not found |
| 400 | Bad Request | Invalid request format |
| 500 | Internal Server Error | Server processing error |
## Data Formats
### CSV Format
- **Content-Type**: `text/csv`
- **Encoding**: UTF-8
- **Delimiter**: Comma (`,`)
- **Headers**: First row contains column names
### JSON Format
- **Content-Type**: `application/json`
- **Encoding**: UTF-8
- **Structure**: Well-formed JSON objects or arrays
## Rate Limiting
- **Free endpoints**: No rate limiting
- **Paid endpoints**: Rate limited by payment (pay-per-request)
- **Download endpoints**: One download per payment authorization
## Usecases
- [Hyperliquid](pages/usecases/hyperliquid.mdx)
### Hyperliquid
# Hyperliquid
TBD.