# /ask
Source: https://docs.hyreagent.fun/api-reference/ask
Natural language DeFi query — ask anything and the LLM orchestrates data sources to answer.
# POST /ask
The meta-endpoint. Ask any DeFi question in plain English and the LLM orchestrates multiple data sources to build a comprehensive answer. The model has access to real-time context including top chain TVLs and top Meteora pool APRs.
**Price:** \$0.025 per request
**Sources:** DeFiLlama, Meteora, and contextual data from all segments
***
## Parameters
Natural language DeFi question.
***
## Example Request
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/ask \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"query": "What are the best stablecoin yield opportunities on Solana right now?"}'
```
***
## Example Response
```json theme={null}
{
"data": {
"query": "What are the best stablecoin yield opportunities on Solana right now?",
"context": {
"top_chains_by_tvl": [
{ "name": "Ethereum", "tvl_usd": 62800000000 },
{ "name": "Solana", "tvl_usd": 12400000000 }
],
"top_meteora_pools_by_apr": [
{ "name": "SOL-USDC", "apr_pct": 162.5, "tvl_usd": 4200000 },
{ "name": "USDC-USDT", "apr_pct": 24.5, "tvl_usd": 8200000 }
]
},
"available_endpoints": [
"/defi/yields",
"/lp/meteora/pools",
"/lp/meteora/pools/recommend"
]
},
"insight": "Best stablecoin yields on Solana: (1) Meteora USDC-USDT at 24.5% APY with $8.2M TVL — pure fee yield, no IL risk. (2) Marinade USDC pools at ~12% with MNDE token incentives. (3) Drift USDC lending at ~8%. For deeper pool analysis, try /lp/meteora/pools?sort=apr with stablecoin filter.",
"signal": "high_yield",
"confidence": 0.88,
"sources": ["defillama", "meteora-dlmm"],
"model_used": "serv/google/gemini-3.5-flash",
"latency_ms": 1456,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## What You Can Ask
* "What are the highest yield stablecoin pools?"
* "Compare TVL growth between Solana and Base this month"
* "Is the current yield on Meteora SOL-USDC sustainable?"
* "Should I buy this token? \[paste mint address]"
* "What tokens are smart money accumulating?"
* "How risky is this PumpFun launch?"
* "Is this wallet worth following?"
* "Who are the top traders this week?"
* "What's the best LP strategy for SOL-USDC with \$5000?"
* "Should I bridge my USDC from Solana to Arbitrum for better yield?"
* "What's the cheapest way to bridge 10,000 USDC?"
***
## How It Differs from Other Endpoints
| Feature | /ask | Specific endpoints |
| ------------- | ------------------------------ | --------------------------- |
| Input | Natural language question | Structured parameters |
| Data scope | Cross-endpoint context | Single data source |
| Best for | Exploration, complex questions | Automation, precise queries |
| Response time | Slower (\~1-2s) | Faster (\~300-500ms) |
| Price | \$0.025 (flat) | $0.001 - $0.050 (varies) |
For automated pipelines, prefer the specific endpoints (e.g., `/defi/yields`, `/lp/pools`). They are faster, cheaper, and return structured data. Use `/ask` for one-off research questions or when you're not sure which endpoint to call.
***
## Endpoint Routing Hint
The response includes an `available_endpoints` field listing the specific HYRE endpoints relevant to your question. Use this to transition from exploratory `/ask` queries to precise endpoint calls.
# TVL Rankings
Source: https://docs.hyreagent.fun/api-reference/defi/tvl
Total Value Locked across DeFi chains with AI trend analysis.
# POST /defi/tvl
Returns Total Value Locked (TVL) rankings across DeFi chains, powered by DeFiLlama data with AI-generated trend analysis.
**Price:** \$0.001 per request
**Signal vocabulary:** `high_yield` | `medium_yield` | `low_yield` | `risky`
**Sources:** DeFiLlama
***
## Parameters
Chain filter. Options: `solana`, `ethereum`, `all`, or any chain name supported by DeFiLlama.
Filter by protocol name (optional).
Maximum number of chains to return (max 50).
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/defi/tvl \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"chain": "all", "limit": 10}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/defi/tvl?chain=all&limit=10" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"chains": [
{ "name": "Ethereum", "tvl_usd": 62800000000, "token_symbol": "ETH" },
{ "name": "Solana", "tvl_usd": 12400000000, "token_symbol": "SOL" },
{ "name": "BSC", "tvl_usd": 5600000000, "token_symbol": "BNB" },
{ "name": "Arbitrum", "tvl_usd": 3200000000, "token_symbol": "ARB" },
{ "name": "Base", "tvl_usd": 2800000000, "token_symbol": "ETH" }
],
"total_tvl_usd": 98200000000,
"filter": { "chain": "all", "protocol": null }
},
"insight": "Solana TVL surged 12% week-over-week driven by memecoin speculation and Meteora LP inflows. Ethereum dominance declined to 64%. Base showing strong growth at $2.8B, up 18% this month.",
"signal": "high_yield",
"confidence": 0.87,
"sources": ["defillama"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 342,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| -------------- | ------ | ------------------------- |
| `name` | string | Chain name |
| `tvl_usd` | number | Total Value Locked in USD |
| `token_symbol` | string | Native gas token symbol |
Data is cached for 15 minutes. TVL figures are sourced from DeFiLlama and include all tracked protocols on each chain.
# Yield Opportunities
Source: https://docs.hyreagent.fun/api-reference/defi/yields
Top yield pools multi-chain sorted by APY with risk assessment.
# POST /defi/yields
Returns the top yield opportunities across all chains, powered by DeFiLlama yield data. Supports filtering by chain, stablecoin status, and minimum APY.
**Price:** \$0.002 per request
**Signal vocabulary:** `high_yield` | `medium_yield` | `low_yield` | `risky`
**Sources:** DeFiLlama
***
## Parameters
Chain filter. Use `all` for cross-chain results.
Set to `true` to show only stablecoin pools.
Minimum APY percentage filter.
Maximum number of pools to return (max 50).
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/defi/yields \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"chain": "solana", "stablecoin": "true", "min_apy": 5, "limit": 10}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/defi/yields?chain=solana&stablecoin=true&min_apy=5&limit=10" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"pools": [
{
"pool": "USDC-USDT",
"project": "Meteora",
"chain": "Solana",
"apy_pct": 24.5,
"tvl_usd": 8200000,
"stablecoin": true,
"il_risk": "none",
"reward_tokens": ["USDC"]
},
{
"pool": "USDC-DAI",
"project": "Marinade",
"chain": "Solana",
"apy_pct": 12.3,
"tvl_usd": 3400000,
"stablecoin": true,
"il_risk": "none",
"reward_tokens": ["MNDE"]
}
],
"filter": {
"chain": "solana",
"stablecoin": true,
"min_apy": 5
}
},
"insight": "Top stablecoin yield on Solana is Meteora's USDC-USDT at 24.5% APY with $8.2M TVL — sustainable fee-based yield with zero IL risk. Marinade's USDC-DAI at 12.3% includes MNDE incentives which may decrease over time.",
"signal": "high_yield",
"confidence": 0.89,
"sources": ["defillama"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 567,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| --------------- | --------- | ----------------------------------- |
| `pool` | string | Pool name / token pair |
| `project` | string | Protocol name |
| `chain` | string | Chain where the pool operates |
| `apy_pct` | number | Annual Percentage Yield |
| `tvl_usd` | number | Total Value Locked in the pool |
| `stablecoin` | boolean | Whether the pool is stablecoin-only |
| `il_risk` | string | Impermanent loss risk level |
| `reward_tokens` | string\[] | Tokens distributed as rewards |
High APY pools (>100%) often rely on token emissions that decrease over time. The AI insight considers yield sustainability when generating the signal.
# Pool Detail
Source: https://docs.hyreagent.fun/api-reference/lp/pool-detail
Deep analytics for a specific Meteora DLMM pool — volume history, fee breakdown, bin distribution.
# POST /lp/pool-detail
Returns detailed analytics for a single Meteora DLMM pool, including volume history, fee breakdown, bin distribution, and position recommendations.
**Price:** \$0.003 per request
**Signal vocabulary:** `add_liquidity` | `hold` | `remove`
**Sources:** Meteora DLMM
***
## Parameters
Meteora DLMM pool address.
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/lp/pool-detail \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"address": "5BVcXj8VaJ5hgNFYnUmxDkRpSWaQj5m9zLJFo3YUrjhk"}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/lp/meteora/pools/5BVcXj8VaJ5hgNFYnUmxDkRpSWaQj5m9zLJFo3YUrjhk" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"pool": {
"address": "5BVc...",
"name": "SOL-USDC",
"bin_step": 1,
"base_fee_pct": 0.01,
"current_price": 150.42,
"tvl_usd": 4200000,
"volume_24h_usd": 18700000,
"volume_7d_usd": 98400000,
"fees_24h_usd": 18700,
"fees_7d_usd": 94200,
"apr_24h_pct": 162.5,
"apr_7d_pct": 128.3,
"active_bin_id": 8234,
"total_positions": 342
},
"volume_history": [
{ "date": "2026-04-16", "volume_usd": 19200000 },
{ "date": "2026-04-15", "volume_usd": 17800000 }
]
},
"insight": "Strong, consistent volume averaging $18.7M/day over the past week. 7d APR at 128% is more sustainable than the 24h spike of 162%. With 342 active positions, liquidity depth is healthy. Good pool for new positions.",
"signal": "add_liquidity",
"confidence": 0.84,
"sources": ["meteora-dlmm"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 678,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| ----------------- | ------- | --------------------------------- |
| `address` | string | Pool contract address |
| `name` | string | Pool name |
| `bin_step` | integer | Price granularity in basis points |
| `base_fee_pct` | number | Base fee percentage per swap |
| `current_price` | number | Current token X/Y price |
| `tvl_usd` | number | Total Value Locked |
| `volume_24h_usd` | number | 24-hour trading volume |
| `volume_7d_usd` | number | 7-day trading volume |
| `fees_24h_usd` | number | 24-hour fee revenue |
| `fees_7d_usd` | number | 7-day fee revenue |
| `apr_24h_pct` | number | APR based on 24h fees |
| `apr_7d_pct` | number | APR based on 7d fees |
| `active_bin_id` | integer | Current active bin |
| `total_positions` | integer | Number of active LP positions |
The 7-day APR is typically more reliable than the 24-hour APR, which can spike during volatile periods. Use the 7d figure for position planning.
# LP Pools
Source: https://docs.hyreagent.fun/api-reference/lp/pools
All Meteora DLMM pools with TVL, volume, fees, and APR analytics.
# POST /lp/pools
Lists Meteora DLMM liquidity pools with real-time analytics. Supports server-side filtering by token, sorting by APR/volume/TVL, and pagination.
**Price:** \$0.001 per request
**Signal vocabulary:** `add_liquidity` | `hold`
**Sources:** Meteora DLMM
***
## Parameters
Sort order. Options: `apr`, `volume`, `tvl`.
Maximum number of pools to return (max 100).
Filter by token mint address.
Filter by base token symbol (e.g., `SOL`).
Filter by quote token symbol (e.g., `USDC`).
Minimum TVL in USD.
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/lp/pools \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"sort": "apr", "limit": 5, "min_tvl": 100000}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/lp/meteora/pools?sort=apr&limit=5" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"pools": [
{
"address": "5BVc...",
"name": "SOL-USDC",
"bin_step": 1,
"base_fee_pct": 0.01,
"tvl_usd": 4200000,
"volume_24h_usd": 18700000,
"fees_24h_usd": 18700,
"apr_pct": 162.5,
"token_x": { "symbol": "SOL", "mint": "So111..." },
"token_y": { "symbol": "USDC", "mint": "EPjFW..." }
}
],
"total_pools": 1,
"sort": "apr",
"filter": { "min_tvl": 100000 }
},
"insight": "Top SOL-USDC pool showing 162% APR with $4.2M TVL — strong fee generation from high volume. Fee/TVL ratio of 0.44% daily is sustainable given current market volatility.",
"signal": "add_liquidity",
"confidence": 0.86,
"sources": ["meteora-dlmm"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 456,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| ---------------- | ------- | --------------------------------- |
| `address` | string | Pool contract address |
| `name` | string | Pool name (e.g., "SOL-USDC") |
| `bin_step` | integer | Bin step size (price granularity) |
| `base_fee_pct` | number | Base fee percentage |
| `tvl_usd` | number | Total Value Locked in USD |
| `volume_24h_usd` | number | 24-hour trading volume in USD |
| `fees_24h_usd` | number | 24-hour fees generated in USD |
| `apr_pct` | number | Annualized Percentage Rate |
| `token_x` | object | Base token (symbol + mint) |
| `token_y` | object | Quote token (symbol + mint) |
# Pool Recommendations
Source: https://docs.hyreagent.fun/api-reference/lp/pools-recommend
AI-powered pool recommendation for a token pair with strategy guidance.
# POST /lp/pools-recommend
Returns the optimal Meteora DLMM pool for a given token pair, along with AI-generated strategy recommendations including distribution type, risk assessment, and expected APR range.
**Price:** \$0.008 per request
**Signal vocabulary:** `add_liquidity` | `hold`
**Sources:** Meteora DLMM
***
## Parameters
Base token symbol (e.g., `SOL`, `JUP`).
Quote token symbol (e.g., `USDC`, `USDT`).
Distribution strategy. Options: `spot`, `curve`, `bidask`.
Risk tolerance. Options: `low`, `mid`, `high`.
***
## Example Request
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/lp/pools-recommend \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"base": "SOL", "quote": "USDC", "strategy": "spot", "risk": "mid"}'
```
***
## Example Response
```json theme={null}
{
"data": {
"recommended_pool": {
"address": "5BVc...",
"name": "SOL-USDC (1bp)",
"bin_step": 1,
"tvl_usd": 4200000,
"apr_pct": 162.5,
"volume_24h_usd": 18700000
},
"strategy": {
"distribution": "spot",
"suggested_range_pct": 5.0,
"risk_level": "mid",
"expected_apr_low": 80,
"expected_apr_high": 200,
"il_risk": "moderate"
},
"alternatives": [
{
"address": "7kQw...",
"name": "SOL-USDC (5bp)",
"bin_step": 5,
"tvl_usd": 2100000,
"apr_pct": 95.2
}
]
},
"insight": "The 1bp SOL-USDC pool is the top pick — highest volume drives strong fee revenue despite tight bins. Spot distribution with +/-5% range captures 90% of recent price action. IL risk is moderate given SOL's current volatility regime.",
"signal": "add_liquidity",
"confidence": 0.91,
"sources": ["meteora-dlmm"],
"model_used": "serv/google/gemini-3.5-flash",
"latency_ms": 892,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Strategy Types
| Strategy | Description | Best For |
| -------- | --------------------------------------------- | --------------------------------- |
| `spot` | Uniform distribution around current price | General-purpose, most common |
| `curve` | Bell curve distribution (concentrated center) | Stable pairs, range-bound markets |
| `bidask` | One-sided liquidity (buy or sell wall) | Directional conviction, DCA |
The recommendation considers current volume patterns, fee generation, TVL depth, and historical APR stability when selecting the optimal pool and strategy.
# Flow Intelligence
Source: https://docs.hyreagent.fun/api-reference/nansen/flow-intel
Smart trader vs whale vs KOL net-flow for a token over configurable timeframes.
# POST /nansen/flow-intel
Returns net-flow data for a specific token, broken down by smart money category: smart traders, whales, and KOLs (Key Opinion Leaders). Powered by Nansen's institutional-grade wallet labeling.
**Price:** \$0.020 per request
**Signal vocabulary:** `accumulate` | `distribute` | `ignore`
**Sources:** Nansen
***
## Parameters
Blockchain to query. Options: `ethereum`, `solana`, `base`, `arbitrum`.
Token contract address on the specified chain.
Analysis timeframe. Options: `5m`, `1h`, `6h`, `12h`, `1d`, `7d`.
***
## Example Request
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/nansen/flow-intel \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{
"chain": "solana",
"token_address": "So11111111111111111111111111111111111111112",
"timeframe": "7d"
}'
```
***
## Example Response
```json theme={null}
{
"data": {
"token": "So11111111111111111111111111111111111111112",
"chain": "solana",
"timeframe": "7d",
"flows": {
"smart_traders": {
"net_flow_usd": 2400000,
"buy_volume_usd": 5200000,
"sell_volume_usd": 2800000,
"unique_wallets": 34
},
"whales": {
"net_flow_usd": -800000,
"buy_volume_usd": 3100000,
"sell_volume_usd": 3900000,
"unique_wallets": 12
},
"kols": {
"net_flow_usd": 150000,
"buy_volume_usd": 320000,
"sell_volume_usd": 170000,
"unique_wallets": 8
}
},
"total_net_flow_usd": 1750000
},
"insight": "Smart traders are aggressively accumulating SOL with $2.4M net inflow over 7 days. Whales are slightly distributing (-$800K), but this is offset by broad-based smart money buying. KOL activity is neutral. Overall bullish setup.",
"signal": "accumulate",
"confidence": 0.85,
"sources": ["nansen"],
"model_used": "gemini-2.5-flash",
"latency_ms": 1234,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Flow Categories
| Category | Description |
| ----------------- | ----------------------------------------------------------------------- |
| **Smart Traders** | Wallets with consistently profitable trading history, labeled by Nansen |
| **Whales** | Large-balance wallets (typically >\$1M in holdings) |
| **KOLs** | Key Opinion Leaders — wallets linked to known crypto influencers |
Positive net flow indicates accumulation (more buying than selling). Negative net flow indicates distribution. The AI weighs smart trader flow more heavily than whale flow when generating the signal.
# Token Screener
Source: https://docs.hyreagent.fun/api-reference/nansen/screener
Find tokens that smart money is actively accumulating across chains.
# POST /nansen/token-screener
Screens tokens across multiple chains to find those with significant smart money activity. Powered by Nansen's wallet labels and flow data.
**Price:** \$0.025 per request
**Signal vocabulary:** `accumulate` | `distribute` | `ignore`
**Sources:** Nansen
***
## Parameters
Comma-separated chain list. Options: `ethereum`, `solana`, `base`, `arbitrum`.
Only show tokens with smart money activity.
Maximum token age in days. Useful for finding new tokens.
Minimum market cap in USD.
Maximum market cap in USD.
Maximum number of tokens to return (max 50).
***
## Example Request
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/nansen/token-screener \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{
"chains": "solana,base",
"only_smart_money": true,
"market_cap_min": 1000000,
"market_cap_max": 100000000,
"limit": 10
}'
```
***
## Example Response
```json theme={null}
{
"data": {
"tokens": [
{
"symbol": "EXAMPLE",
"chain": "solana",
"address": "ExAm...",
"market_cap_usd": 24500000,
"price_usd": 0.245,
"smart_money_net_flow_7d_usd": 890000,
"smart_money_wallets": 12,
"whale_wallets": 4,
"token_age_days": 14
}
],
"total_matches": 1,
"filters": {
"chains": ["solana", "base"],
"only_smart_money": true,
"market_cap_min": 1000000,
"market_cap_max": 100000000
}
},
"insight": "EXAMPLE on Solana stands out — 12 smart money wallets accumulated $890K in 7 days. Market cap at $24.5M with only 14 days of age. Early-stage accumulation pattern consistent with pre-narrative positioning.",
"signal": "accumulate",
"confidence": 0.82,
"sources": ["nansen"],
"model_used": "gemini-2.5-flash",
"latency_ms": 1678,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| ----------------------------- | ------ | ------------------------------------- |
| `symbol` | string | Token ticker symbol |
| `chain` | string | Blockchain where the token lives |
| `address` | string | Token contract address |
| `market_cap_usd` | number | Current market capitalization |
| `price_usd` | number | Current token price |
| `smart_money_net_flow_7d_usd` | number | Net smart money flow over 7 days |
| `smart_money_wallets` | number | Number of smart money wallets holding |
| `whale_wallets` | number | Number of whale wallets holding |
| `token_age_days` | number | Days since token creation |
The screener is most useful for mid-cap discovery ($1M-$100M market cap). For micro-caps, use the Trenches endpoints. For large-caps, the flow patterns are well-known and less alpha-generating.
# Wallet Intelligence (Nansen)
Source: https://docs.hyreagent.fun/api-reference/nansen/wallet-intel
Deep wallet profile with PnL history, archetype, and recent smart trades.
# POST /nansen/wallet-intel
Deep intelligence profile for any wallet on supported chains, powered by Nansen's wallet labels and trading data. Includes PnL summary, trader archetype classification, and recent smart trades.
**Price:** \$0.050 per request
**Signal vocabulary:** `follow` | `ignore`
**Sources:** Nansen
***
## Parameters
Blockchain to query. Options: `ethereum`, `solana`, `base`, `arbitrum`.
Wallet address to profile.
***
## Example Request
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/nansen/wallet-intel \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{
"chain": "solana",
"address": "vhu9Nc7EQi6dpvk9R6GyrDjgrgnR2oyfRAeeYVmQCAp"
}'
```
***
## Example Response
```json theme={null}
{
"data": {
"address": "vhu9Nc7EQi6dpvk9R6GyrDjgrgnR2oyfRAeeYVmQCAp",
"chain": "solana",
"labels": ["Smart Money", "Early Adopter"],
"pnl_summary": {
"realized_pnl_usd": 142000,
"unrealized_pnl_usd": 28400,
"total_pnl_usd": 170400,
"win_rate_pct": 71.2,
"total_trades": 234
},
"archetype": "smart_degen",
"recent_smart_trades": [
{
"token": "BONK",
"action": "buy",
"amount_usd": 15000,
"timestamp": "2026-04-16T14:30:00.000Z",
"pnl_usd": 4200
}
],
"portfolio_value_usd": 89000,
"active_since": "2024-03-15"
},
"insight": "Labeled 'Smart Money' by Nansen with $170K total PnL across 234 trades. 71% win rate with a smart degen archetype — takes high-conviction bets on meme coins. Recent BONK buy netted $4.2K. Portfolio at $89K. Active since March 2024.",
"signal": "follow",
"confidence": 0.90,
"sources": ["nansen"],
"model_used": "gemini-2.5-flash",
"latency_ms": 2345,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Nansen Labels
Common Nansen wallet labels that may appear:
| Label | Description |
| ------------- | --------------------------------------- |
| Smart Money | Consistently profitable trading history |
| Whale | Large-balance wallet (>\$1M) |
| Fund | Known investment fund or DAO treasury |
| Early Adopter | Early activity in emerging protocols |
| DEX Trader | High-frequency DEX trading activity |
| NFT Trader | Significant NFT trading volume |
***
## Differences from /traders/wallet-intel
| Feature | /traders/wallet-intel | /nansen/wallet-intel |
| ----------- | ------------------------- | ----------------------------------------- |
| Data source | Solana RPC (raw) | Nansen (labeled) |
| Chains | Solana only | Ethereum, Solana, Base, Arbitrum |
| Labels | AI-generated archetype | Nansen-verified labels |
| Price | \$0.012 | \$0.050 |
| Best for | Quick Solana wallet check | Cross-chain, institutional-grade analysis |
The Nansen endpoint costs more because it queries Nansen's commercial API, which provides institutional-grade wallet labeling and classification. For Solana-only analysis at a lower price, use `/traders/wallet-intel`.
# API Overview
Source: https://docs.hyreagent.fun/api-reference/overview
Base URL, authentication, response format, and signal vocabulary for all HYRE endpoints.
# API Overview
## Base URL
```
https://mpp.hyreagent.fun
```
All endpoints are available on three chains via URL prefixes:
| Chain | Prefix | Example |
| ------ | ---------- | ----------------- |
| Solana | `/` (root) | `/defi/tvl` |
| Base | `/base/` | `/base/defi/tvl` |
| SKALE | `/skale/` | `/skale/defi/tvl` |
***
## Authentication
HYRE uses **x402 payment** instead of API keys. Every paid request must include an `X-PAYMENT` header with a signed payment payload.
1. Call the endpoint without payment to receive a 402 challenge.
2. Sign the payment with your wallet.
3. Retry with the `X-PAYMENT` header attached.
See [x402 Protocol](/payment/x402-protocol) for details.
***
## Standard Response Format
Every paid endpoint returns the `HyreResponse` envelope:
```json theme={null}
{
"data": {
// Structured data from upstream sources
// Shape varies per endpoint
},
"insight": "AI-generated actionable summary (1-2 sentences)",
"signal": "actionable_signal",
"confidence": 0.87,
"sources": ["defillama", "jupiter"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 342,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
Structured data from upstream sources. Shape varies per endpoint.
AI-generated actionable insight in 1-2 sentences. `null` if all LLM models failed (HTTP 206).
Decision signal for the caller. Vocabulary depends on the endpoint segment.
LLM confidence in the signal, from 0.0 to 1.0.
List of upstream data sources used (e.g., `["defillama"]`, `["solana-rpc", "jupiter"]`).
Name of the LLM model that produced the insight. `null` on HTTP 206.
Total response time in milliseconds (data fetch + LLM + response assembly).
ISO 8601 timestamp of the response.
***
## Signal Vocabulary
Each endpoint segment uses a specific set of signals:
| Segment | Signals | Meaning |
| ------------------------- | -------------------------------------------------- | ---------------------------- |
| **Trenches** | `snipe`, `watch`, `avoid` | Token action recommendation |
| **Trenches** (graduation) | `graduate_soon`, `watch` | Bonding curve urgency |
| **Traders** | `follow`, `ignore` | Wallet copy-trade worthiness |
| **Traders** (holdings) | `accumulate`, `distribute`, `ignore` | Position momentum |
| **LPs** | `add_liquidity`, `rebalance`, `hold`, `remove` | LP position action |
| **DeFi** | `high_yield`, `medium_yield`, `low_yield`, `risky` | Yield risk assessment |
| **deBridge** (quote) | `execute`, `wait`, `avoid` | Bridge execution timing |
| **deBridge** (yield) | `migrate`, `stay`, `wait` | Cross-chain move decision |
| **Nansen** | `follow`, `ignore`, `accumulate`, `distribute` | Smart money action |
***
## HTTP Status Codes
| Code | Meaning |
| ----- | --------------------------------------------------- |
| `200` | Success -- full AI-enriched response |
| `206` | Partial -- raw data returned, LLM enrichment failed |
| `402` | Payment Required -- attach x402 payment header |
| `400` | Bad Request -- invalid parameters |
| `404` | Not Found -- endpoint does not exist |
| `500` | Server Error -- unexpected failure |
***
## Request Methods
All endpoints support both `GET` and `POST`:
Parameters in the JSON body. Preferred for x402 compatibility.
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/trenches/token-verdict \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"mint": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"}'
```
Parameters in the URL path and query string. Supported for backward compatibility.
```bash theme={null}
curl "https://mpp.hyreagent.fun/trenches/token/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/verdict" \
-H "X-PAYMENT: "
```
***
## OpenAPI Specification
The full OpenAPI 3.1 spec is available at:
```
https://mpp.hyreagent.fun/openapi.json
```
It includes `x-payment-info` extensions for every endpoint with pricing, network details, and facilitator URLs.
# Token Whales
Source: https://docs.hyreagent.fun/api-reference/traders/token-whales
Whale activity — largest holders and accumulation/distribution flows for a token.
# POST /traders/token-whales
Identifies the largest holders (whales) of any Solana token and analyzes whether they are accumulating or distributing. Useful for gauging smart money sentiment.
**Price:** \$0.003 per request
**Signal vocabulary:** `accumulate` | `distribute` | `ignore`
**Sources:** Solana RPC, Jupiter
***
## Parameters
Solana token mint address.
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/traders/token-whales \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"mint": "So11111111111111111111111111111111111111112"}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/traders/token/So11111111111111111111111111111111111111112/whales" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"mint": "So11111111111111111111111111111111111111112",
"top_holders": [
{
"address": "9WzDX...",
"balance": 1250000,
"pct_of_supply": 12.5,
"value_usd": 187500
},
{
"address": "4kPmR...",
"balance": 890000,
"pct_of_supply": 8.9,
"value_usd": 133500
}
],
"concentration": {
"top_5_pct": 38.2,
"top_10_pct": 52.1,
"top_20_pct": 67.8
},
"total_holders": 4231
},
"insight": "Top 5 wallets control 38% of supply — moderate concentration. The largest holder (9WzDX) increased their position by 15% this week, signaling active accumulation.",
"signal": "accumulate",
"confidence": 0.81,
"sources": ["solana-rpc", "jupiter"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 876,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| --------------- | ------ | ------------------------------- |
| `address` | string | Wallet address |
| `balance` | number | Token balance (human units) |
| `pct_of_supply` | number | Percentage of total supply held |
| `value_usd` | number | Current USD value of holdings |
| Field | Type | Description |
| ------------ | ------ | --------------------------------- |
| `top_5_pct` | number | Percentage held by top 5 wallets |
| `top_10_pct` | number | Percentage held by top 10 wallets |
| `top_20_pct` | number | Percentage held by top 20 wallets |
# Top Wallets
Source: https://docs.hyreagent.fun/api-reference/traders/top-wallets
Top performing wallets leaderboard ranked by PnL.
# POST /traders/top-wallets
Leaderboard of the highest-performing Solana wallets ranked by realized PnL over a given period. Useful for identifying alpha wallets to track and copy-trade.
**Price:** \$0.008 per request
**Signal vocabulary:** `follow` | `ignore`
**Sources:** Solana RPC
***
## Parameters
Time period for the leaderboard. Options: `24h`, `7d`.
Maximum number of wallets to return (max 50).
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/traders/top-wallets \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"period": "24h", "limit": 10}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/traders/top-wallets?period=24h&limit=10" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"period": "24h",
"wallets": [
{
"address": "7pKm2...",
"pnl_usd": 45200,
"win_rate_pct": 82.1,
"trades": 23,
"best_token": "BONK",
"best_trade_pnl_usd": 18400
},
{
"address": "3vFq8...",
"pnl_usd": 31800,
"win_rate_pct": 76.5,
"trades": 41,
"best_token": "WIF",
"best_trade_pnl_usd": 9200
}
],
"total_wallets_analyzed": 5000
},
"insight": "Top performer 7pKm2 made $45K in 23 trades — a sniper pattern with 82% hit rate. Notable that 3 of the top 10 wallets share similar entry timing, suggesting alpha group coordination.",
"signal": "follow",
"confidence": 0.83,
"sources": ["solana-rpc"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 1567,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| -------------------- | ------ | ------------------------------------------ |
| `address` | string | Wallet address |
| `pnl_usd` | number | Net realized PnL in USD for the period |
| `win_rate_pct` | number | Percentage of profitable trades |
| `trades` | number | Total trades in the period |
| `best_token` | string | Token with the highest single-trade profit |
| `best_trade_pnl_usd` | number | PnL of the best single trade |
# Wallet Intelligence
Source: https://docs.hyreagent.fun/api-reference/traders/wallet-intel
30-day wallet intelligence profile with trader archetype and copy-worthiness score.
# POST /traders/wallet-intel
Deep intelligence profile for any Solana wallet. Analyzes 30 days of transaction history to determine the trader's archetype, win rate, specialty, and copy-worthiness. The most comprehensive wallet analysis endpoint.
**Price:** \$0.012 per request
**Signal vocabulary:** `follow` | `ignore`
**Sources:** Solana RPC, Jupiter
***
## Parameters
Solana wallet address to profile.
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/traders/wallet-intel \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"address": "vhu9Nc7EQi6dpvk9R6GyrDjgrgnR2oyfRAeeYVmQCAp"}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/traders/wallet/vhu9Nc7EQi6dpvk9R6GyrDjgrgnR2oyfRAeeYVmQCAp/intel" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"address": "vhu9Nc7EQi6dpvk9R6GyrDjgrgnR2oyfRAeeYVmQCAp",
"period": "30d",
"archetype": "sniper",
"win_rate_pct": 73.2,
"total_trades": 142,
"avg_hold_hours": 4.2,
"net_pnl_usd": 12400,
"best_trade_pnl_usd": 3200,
"worst_trade_pnl_usd": -890,
"specialty": "meme_coins",
"copy_worthiness": 7.8,
"current_positions": 4,
"portfolio_value_usd": 28500
},
"insight": "This is a high-frequency sniper wallet with a 73% win rate on meme coins. Average hold time of 4.2 hours suggests a scalping strategy. Copy-worthiness score 7.8/10 — strong risk-adjusted returns with consistent execution.",
"signal": "follow",
"confidence": 0.88,
"sources": ["solana-rpc", "jupiter"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 2103,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Trader Archetypes
The AI classifies wallets into these archetypes:
| Archetype | Description |
| -------------- | --------------------------------------------------- |
| `sniper` | Buys tokens within minutes of launch, exits quickly |
| `swing_trader` | Holds positions for hours to days |
| `accumulator` | Gradually builds large positions over time |
| `whale` | Large capital, moves markets with single trades |
| `degen` | High-frequency, high-risk meme coin trading |
| `lp_farmer` | Primarily provides liquidity for yield |
| `inactive` | Fewer than 5 trades in the analysis period |
***
## Copy-Worthiness Score
The copy-worthiness score (0-10) factors in:
| Factor | Weight |
| -------------------------- | ------ |
| Win rate | 30% |
| Risk-adjusted returns | 25% |
| Consistency (low variance) | 20% |
| Trade frequency | 15% |
| Max drawdown | 10% |
A score above 7.0 is considered "follow-worthy". Scores below 4.0 suggest the wallet is not worth copying. The signal field reflects this threshold.
# Graduating Tokens
Source: https://docs.hyreagent.fun/api-reference/trenches/graduating
Tokens near bonding curve graduation (>85% complete).
# POST /trenches/graduating
Finds PumpFun tokens that are close to graduating from the bonding curve (>85% progress). These tokens are about to transition to Raydium DEX trading -- a critical event that often triggers price action.
**Price:** \$0.003 per request
**Signal vocabulary:** `graduate_soon` | `watch`
**Sources:** PumpPortal, Solana RPC
***
## Parameters
Maximum number of graduating tokens to return.
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/trenches/graduating \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"limit": 5}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/trenches/graduating?limit=5" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"graduating": [
{
"mint": "9qWV3z...",
"name": "GraduatingToken",
"symbol": "GRAD",
"progress_pct": 92.4,
"sol_in_curve": 378.2,
"estimated_hours_remaining": 1.2,
"holders": 1240,
"urgency": "high"
},
{
"mint": "3kFm8B...",
"name": "AlmostThere",
"symbol": "ALMT",
"progress_pct": 87.1,
"sol_in_curve": 312.8,
"estimated_hours_remaining": 6.4,
"holders": 890,
"urgency": "medium"
}
],
"total_found": 2
},
"insight": "GRAD is 1.2 hours from graduation with strong organic buying. 1,240 holders and no dominant sniper wallets. ALMT is further out at 6.4 hours with moderate momentum.",
"signal": "graduate_soon",
"confidence": 0.85,
"sources": ["pumpportal", "solana-rpc"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 1234,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| --------------------------- | ------ | ---------------------------------------- |
| `mint` | string | Token mint address |
| `name` | string | Token name |
| `symbol` | string | Token ticker |
| `progress_pct` | number | Bonding curve completion percentage |
| `sol_in_curve` | number | Total SOL deposited in the bonding curve |
| `estimated_hours_remaining` | number | Estimated hours until graduation |
| `holders` | number | Current holder count |
| `urgency` | string | `high` (>90%), `medium` (85-90%) |
Graduation occurs when the bonding curve reaches 100% and the token migrates to Raydium. This typically triggers a price spike as DEX trading opens.
# New Tokens
Source: https://docs.hyreagent.fun/api-reference/trenches/new-tokens
Real-time PumpFun token launches with AI snipe signal.
# POST /trenches/new-tokens
Fetches the latest PumpFun token launches from the PumpPortal Durable Object cache. Each token includes metadata, dev wallet, bonding curve key, and an AI-generated snipe/watch/avoid signal.
**Price:** \$0.008 per request
**Signal vocabulary:** `snipe` | `watch` | `avoid`
**Sources:** PumpPortal
***
## Parameters
Maximum number of tokens to return (max 100).
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/trenches/new-tokens \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"limit": 5}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/trenches/new-tokens?limit=5" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"tokens": [
{
"mint": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"name": "ExampleToken",
"symbol": "EXT",
"platform": "pumpfun",
"initial_buy_sol": 1.5,
"market_cap_sol": 42.3,
"created_at": "2026-04-17T10:25:00.000Z",
"bonding_curve_key": "BcYvE8s...",
"dev_wallet": "vhu9Nc7E..."
}
]
},
"insight": "3 of 5 recent launches show insider bundling patterns. EXT has the cleanest launch — solo dev, no sniper wallets in first 3 blocks.",
"signal": "watch",
"confidence": 0.74,
"sources": ["pumpportal"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 289,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Data Fields
| Field | Type | Description |
| ------------------- | ------ | ---------------------------------- |
| `mint` | string | Solana token mint address |
| `name` | string | Token name |
| `symbol` | string | Token ticker symbol |
| `platform` | string | Launch platform (always `pumpfun`) |
| `initial_buy_sol` | number | Dev's initial buy in SOL |
| `market_cap_sol` | number | Current market cap in SOL |
| `created_at` | string | ISO 8601 creation timestamp |
| `bonding_curve_key` | string | Bonding curve account address |
| `dev_wallet` | string | Creator's wallet address |
# Token Verdict
Source: https://docs.hyreagent.fun/api-reference/trenches/token-verdict
Full AI verdict combining holders, snipers, dev history, and bonding curve data.
# POST /trenches/token-verdict
Comprehensive risk assessment for any PumpFun token. Combines data from multiple sources -- holder distribution, sniper detection, dev wallet history, bonding curve progress, and metadata -- into a single AI verdict.
This is the most thorough token analysis endpoint, combining the data from `/trenches/token`, `/trenches/token-snipers`, and `/trenches/curve` into one call.
**Price:** \$0.015 per request
**Signal vocabulary:** `snipe` | `watch` | `avoid`
**Sources:** Solana RPC, PumpPortal
***
## Parameters
Solana token mint address.
Bonding curve account address. Optional -- if omitted, the API attempts to derive it from the mint.
***
## Example Request
```bash curl theme={null}
curl -X POST https://mpp.hyreagent.fun/trenches/token-verdict \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"mint": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"}'
```
```bash GET (legacy) theme={null}
curl "https://mpp.hyreagent.fun/trenches/token/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/verdict" \
-H "X-PAYMENT: "
```
***
## Example Response
```json theme={null}
{
"data": {
"token": {
"mint": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"name": "ExampleToken",
"symbol": "EXT",
"holders": 847,
"top_holders_pct": 34.2,
"dev_wallet": "vhu9Nc7E...",
"dev_holds_pct": 8.1,
"freeze_authority": null,
"mint_authority": null
},
"snipers": {
"count": 3,
"total_pct": 12.4,
"risk_level": "medium"
},
"curve": {
"progress_pct": 72.3,
"sol_in_curve": 234.5,
"estimated_graduation_hours": 4.2
}
},
"insight": "EXT shows medium risk. 3 sniper wallets hold 12.4% — not catastrophic but worth monitoring. Dev wallet retains 8.1% with no freeze/mint authority. Bonding curve at 72% suggests graduation in ~4 hours. Top 5 holders concentrated at 34%.",
"signal": "watch",
"confidence": 0.79,
"sources": ["solana-rpc", "pumpportal"],
"model_used": "serv/google/gemini-3.5-flash",
"latency_ms": 1847,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Verdict Components
The AI considers these factors when generating the verdict:
| Factor | Weight | Description |
| ------------------------ | -------- | ------------------------------------------------------- |
| Sniper concentration | High | Wallets that bought in the first 3 blocks |
| Dev wallet holdings | High | Percentage of supply held by creator |
| Freeze/mint authority | Critical | Whether the dev can freeze accounts or mint more tokens |
| Top holder concentration | Medium | How much the top 5 wallets control |
| Bonding curve progress | Medium | How close the token is to graduation |
| Holder count | Low | More holders generally means more organic interest |
This endpoint makes multiple RPC calls and is the slowest in the Trenches segment (\~1-2s latency). For faster but narrower analysis, use the individual endpoints (`/trenches/token`, `/trenches/token-snipers`, `/trenches/curve`).
# Data Sources
Source: https://docs.hyreagent.fun/architecture/data-sources
Upstream data providers powering HYRE's DeFi intelligence endpoints.
# Data Sources
HYRE aggregates data from multiple free, ToS-compliant sources. No paid API keys are required for upstream data -- only the LLM providers and Nansen require authentication.
***
## Source Overview
| Source | Data Type | Endpoints | Rate Limits |
| ------------------------ | ---------------------------------------------- | ---------------------- | --------------------------------- |
| **PumpPortal** | PumpFun token launches | Trenches | Cached via Durable Object |
| **Solana RPC** | On-chain data (accounts, signatures, balances) | Trenches, Traders, LPs | Private RPC (no public RPC limit) |
| **Jupiter Price API v2** | Real-time token prices | Traders, LPs | Public, generous limits |
| **Meteora DLMM API** | LP pool analytics | LP Analytics | Public, generous limits |
| **DeFiLlama** | TVL + yield data | DeFi, deBridge | Public, no auth required |
| **Nansen** | Smart money labels, flows, PnL | Smart Money | API key required |
| **deBridge DLN** | Cross-chain bridge quotes | deBridge | Public, no auth required |
| **Bags.fm** | Meteora DBC token launches | Trenches | Public |
***
## PumpPortal
PumpPortal provides real-time data on PumpFun token launches -- new token creations, bonding curve progress, and graduation events.
**Architecture:** A Cloudflare Durable Object maintains an in-memory cache of recent tokens. A cron job (every 5 minutes) fetches new tokens from Jupiter's unknown token list and ingests them into the DO. The DO also accepts manual POST ingestion via `/admin/feed`.
**Why not WebSocket?** Cloudflare Workers cannot maintain persistent WebSocket client connections. The HTTP-based Durable Object pattern provides equivalent functionality within CF's execution model.
| Property | Value |
| ---------------- | ---------------------------------------------- |
| Cache type | Durable Object (in-memory) |
| Refresh interval | 5 minutes (cron) |
| Data freshness | 30 seconds (cache TTL) |
| Endpoints served | `/trenches/new-tokens`, `/trenches/graduating` |
***
## Solana RPC
HYRE uses a **private Solana RPC endpoint** (not public RPC) because Cloudflare Workers IP ranges are blocked by public Solana RPC providers.
The RPC is used for:
* `getAccountInfo` -- Token metadata, bonding curve state
* `getTokenLargestAccounts` -- Top holders / whale detection
* `getSignaturesForAddress` -- Transaction history for PnL calculation
* `getTokenAccountsByOwner` -- Wallet position scanning
| Property | Value |
| -------- | ------------------------------------------------- |
| Protocol | HTTP JSON-RPC |
| Provider | Private (configured via `SOLANA_RPC_URL` env var) |
| Failover | Multiple RPC URLs supported |
| Used by | Trenches, Traders, LPs |
***
## Jupiter Price API v2
Jupiter provides real-time token prices on Solana. HYRE uses the v2 API for:
* Current USD prices for any SPL token
* Batch price lookups for portfolio valuation
* Token metadata (name, symbol, decimals)
```
GET https://api.jup.ag/price/v2?ids=So11111111111111111111111111111111111111112
```
***
## Meteora DLMM API
Meteora's DLMM API provides liquidity pool analytics:
* Pool list with TVL, volume, fees, and APR
* Individual pool detail with bin distribution
* Server-side filtering and sorting
```
GET https://dlmm.datapi.meteora.ag/pair/all_with_pagination
```
| Property | Value |
| ---------------- | --------------------------------------------------------------------------- |
| Base URL | `https://dlmm.datapi.meteora.ag` |
| Auth | None required |
| Data | Pool TVL, volume, fees, APR, bin distribution |
| Endpoints served | `/lp/pools`, `/lp/pool-detail`, `/lp/pools-recommend`, `/lp/pools-strategy` |
***
## DeFiLlama
DeFiLlama provides cross-chain DeFi data:
* Chain TVL rankings (`api.llama.fi/v2/chains`)
* Yield pool data (`yields.llama.fi/pools`)
* Protocol TVL breakdowns
| Property | Value |
| ---------------- | ------------------------------------------------------ |
| Base URLs | `https://api.llama.fi`, `https://yields.llama.fi` |
| Auth | None required |
| Cache TTL | 15 minutes (TVL), 5 minutes (yields) |
| Endpoints served | `/defi/tvl`, `/defi/yields`, `/debridge/yield-migrate` |
***
## Nansen
Nansen provides institutional-grade smart money intelligence:
* Token screener by smart money activity
* Per-token flow intelligence (smart traders vs whales vs KOLs)
* PnL leaderboards
* Deep wallet profiles
| Property | Value |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| Auth | API key required (`NANSEN_API_KEY`) |
| Chains | Ethereum, Solana, Base, Arbitrum |
| Endpoints served | `/nansen/token-screener`, `/nansen/flow-intel`, `/nansen/pnl-leaderboard`, `/nansen/wallet-intel` |
***
## deBridge DLN
deBridge's DLN (Decentralized Liquidity Network) provides cross-chain swap quotes:
* Route estimation with fees and slippage
* Multi-chain support (Solana, Ethereum, Arbitrum, Base, etc.)
```
GET https://dln.debridge.finance/v1.0/dln/order/quote
```
| Property | Value |
| ---------------- | -------------------------------------------- |
| Base URL | `https://dln.debridge.finance` |
| Auth | None required |
| Endpoints served | `/debridge/quote`, `/debridge/yield-migrate` |
# LLM Cascade
Source: https://docs.hyreagent.fun/architecture/llm-cascade
Tiered multi-model fallback that ensures every request gets an AI-enriched response.
# LLM Cascade
HYRE enriches every endpoint through a tiered multi-model cascade. Each endpoint
picks a **tier** based on what its output is — a cheap data listing, a heavier
analysis, or a genuine analytical decision. Within a tier, models are tried in
priority order: if one fails (timeout, rate limit, content policy), the next is
tried automatically. If all models fail, raw data is returned with
`insight: null` and HTTP 206 status.
***
## Tiers
| Tier | First model | Typical latency | Used for |
| ----------- | --------------------- | --------------- | ---------------------------------------------------------------------- |
| `fast` | Gemini 2.5 Flash-Lite | \~1–1.5s | High-volume listings & formatting (new tokens, pools, prices, TVL) |
| `quality` | Gemini 2.5 Flash | \~1.5–2.5s | Heavier analysis (Smart Money / Nansen) |
| `reasoning` | OpenServ SERV | \~3.5–5s | Analytical **decisions** — verdicts, recommendations, cross-chain math |
Every tier shares the same fallback chain, so a failure in the primary model
degrades gracefully to the next provider rather than failing the request.
***
## Reasoning Tier — OpenServ SERV
Decision endpoints use [OpenServ SERV Reasoning](https://docs.openserv.ai/serv-reasoning/introduction)
as their primary model. SERV is an OpenAI-compatible gateway that runs a bounded
reasoning pass (BRAID) over an underlying model before answering, which improves
multi-factor judgments and arithmetic-heavy comparisons.
| Setting | Value |
| ------------------ | ------------------------------------------------------- |
| Endpoint | `https://inference-api.openserv.ai/v1/chat/completions` |
| Model | `gemini-flash-latest` |
| `reasoning_effort` | `low` |
| Timeout | 12s |
| `max_tokens` | 2500 |
Reasoning tokens share the completion budget, so `max_tokens` is raised to 2500
on this tier (vs 800 on `fast`/`quality`) to avoid truncating the answer. The
12s timeout gives the reasoning pass headroom above the 8s used elsewhere.
**Endpoints on the reasoning tier:**
| Endpoint | Decision |
| ------------------------------------ | --------------------------------------------- |
| `POST /ask` | Natural-language DeFi reasoning |
| `GET /trenches/token/{mint}/verdict` | `snipe` / `watch` / `avoid` |
| `GET /debridge/quote` | `execute` / `wait` / `avoid` |
| `GET /debridge/yield-migrate` | `migrate` / `stay` / `wait` (break-even math) |
| `GET /lp/meteora/pools/recommend` | Pool recommendation |
| `GET /lp/meteora/pools/strategy` | LP strategy |
| `GET /lp/positions/{id}/rebalance` | `rebalance` / `hold` |
If `SERV_API_KEY` is not configured, these endpoints fall back to the Gemini
cascade automatically — no request fails.
***
## Cascade Order
The fallback chain, in order, after the tier's primary model:
| Priority | Provider / Model | Timeout | Notes |
| -------- | ------------------------------ | ------- | ---------------------------------------------------------- |
| 1 | **SERV** (reasoning tier only) | 12s | Bounded reasoning over Gemini Flash. |
| 2 | Gemini 2.5 Flash-Lite | 8s | Primary for `fast`. Cheap + fast JSON. |
| 3 | Gemini 2.5 Flash | 8s | Primary for `quality`. Stronger analysis. |
| 4 | OpenRouter cascade | 8–10s | Cross-provider resilience (DeepSeek → GLM → Claude Haiku). |
| 5 | Venice AI | 8–10s | Last-resort fallback (DeepSeek V3.2, GLM Flash). |
`fast` starts at Flash-Lite then escalates to Flash; `quality` and `reasoning`
fall back through Flash first. All tiers end with OpenRouter then Venice.
### Chat Agent (Playground)
The Playground chat agent uses a separate model:
| Model | Provider | Use Case |
| --------------------- | --------- | --------------------------------------------------------- |
| Gemini 2.5 Flash-Lite | Google AI | Conversation flow, tool selection, response summarization |
***
## Failure Modes
| Failure | Behavior |
| ----------------------- | ------------------------------------------ |
| Timeout (>8–12s) | Abort and try next model |
| HTTP 429 (rate limit) | Skip and try next model |
| HTTP 5xx (server error) | Skip and try next model |
| Content policy block | Skip and try next model |
| Empty response | Skip and try next model |
| All models fail | Return raw data, `insight: null`, HTTP 206 |
HTTP 206 (Partial Content) indicates the data was fetched successfully but the
LLM enrichment failed. The `data` field contains the full upstream data. The
`signal` field falls back to `neutral` with `confidence: 0`.
***
## LLM Call Configuration
Every LLM call uses these parameters:
```json theme={null}
{
"temperature": 0.3,
"max_tokens": 800,
"response_format": { "type": "json_object" }
}
```
* **Low temperature (0.3)** — Prioritizes consistent, factual output over creative variation.
* **JSON mode** — Forces the model to return valid JSON, parsed into the response envelope.
* **800 token limit** — Keeps insights concise (1–2 sentences) and response times fast.
On the `reasoning` tier, `max_tokens` is raised to **2500** and
`reasoning_effort: "low"` is added, since reasoning tokens share the completion
budget.
***
## System Prompts
Each endpoint segment has a dedicated system prompt that instructs the LLM:
| Segment | Signal Vocabulary | Prompt Focus |
| -------- | ---------------------------------------------------------------------- | ------------------------------------------------------ |
| Trenches | `snipe`, `watch`, `avoid` | Token risk assessment, sniper detection, dev behavior |
| Traders | `follow`, `ignore` | Wallet profitability, copy-trade worthiness |
| LPs | `add_liquidity`, `rebalance`, `hold`, `remove` | Pool APR sustainability, IL risk, range optimization |
| DeFi | `high_yield`, `medium_yield`, `low_yield`, `risky` | TVL trends, yield opportunity assessment |
| deBridge | `execute`, `wait`, `avoid` (quote) / `migrate`, `stay`, `wait` (yield) | Bridge cost efficiency, cross-chain yield comparison |
| Nansen | `follow`, `ignore`, `accumulate`, `distribute` | Smart money flow interpretation, wallet classification |
***
## Response Format
The LLM returns JSON matching this structure:
```json theme={null}
{
"insight": "Solana TVL surged 12% this week, driven by...",
"signal": "high_yield",
"confidence": 0.87
}
```
The `enrich()` function merges this with the raw data. `model_used` reflects the
model that actually answered — e.g. `serv/google/gemini-3.5-flash` on the
reasoning tier, or `gemini-2.5-flash-lite` on the fast tier:
```json theme={null}
{
"data": { ... },
"insight": "Solana TVL surged 12% this week, driven by...",
"signal": "high_yield",
"confidence": 0.87,
"sources": ["defillama"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 342,
"timestamp": "2026-06-10T10:30:00.000Z"
}
```
# Architecture Overview
Source: https://docs.hyreagent.fun/architecture/overview
System architecture of the HYRE Agent API on Cloudflare Workers.
# Architecture Overview
HYRE runs on Cloudflare Workers -- V8 isolates with zero cold starts, deployed globally at 300+ edge locations. The stack is designed for sub-second response times and 100% uptime.
***
## System Diagram
```
Client (agent / browser)
|
x402 Payment Header
|
v
┌─────────────────────────┐
│ Cloudflare Workers │
│ (Hono framework) │
│ │
│ ┌───────────────────┐ │
│ │ x402 Middleware │ │
│ │ (verify payment) │ │
│ └────────┬──────────┘ │
│ │ │
│ ┌────────v──────────┐ │
│ │ Route Handler │ │
│ │ (data fetching) │ │
│ └────────┬──────────┘ │
│ │ │
│ ┌────────v──────────┐ │
│ │ LLM Cascade │ │
│ │ (enrich with AI) │ │
│ └────────┬──────────┘ │
│ │ │
│ ┌────────v──────────┐ │
│ │ Response Builder │ │
│ │ (HyreResponse) │ │
│ └───────────────────┘ │
└─────────────────────────┘
| |
┌─────────┘ └──────────┐
v v
┌─────────────┐ ┌──────────────┐
│ Workers KV │ │ Cloudflare D1│
│ (cache) │ │ (revenue log)│
└─────────────┘ └──────────────┘
```
***
## Core Components
### Hono Framework
HYRE uses [Hono](https://hono.dev) -- a fast, lightweight web framework built for edge runtimes. Hono provides:
* Type-safe route handlers with middleware composition
* CORS, error handling, and request parsing out of the box
* Zero-dependency compatibility with Cloudflare Workers
### Workers KV (Cache)
All data-fetching endpoints cache upstream responses in **Cloudflare Workers KV** with configurable TTLs:
| Data Type | TTL |
| ----------------- | ---------- |
| DeFiLlama TVL | 15 minutes |
| Meteora pool list | 5 minutes |
| Token metadata | 2 minutes |
| Wallet PnL | 2 minutes |
| PumpPortal tokens | 30 seconds |
Cache keys are derived from the endpoint path and query parameters. Cache hits skip both upstream data fetching and LLM enrichment.
### Cloudflare D1 (Database)
Revenue logs are stored in **Cloudflare D1** -- SQLite at the edge. Every paid request logs:
* Endpoint path
* Caller wallet address
* Payment amount
* Payment protocol (x402 chain)
* LLM model used
* Response latency
### Durable Objects
The **PumpPortal Durable Object** maintains an in-memory cache of recent PumpFun token launches:
* HTTP-based (not WebSocket) for CF Workers compatibility
* Fed by a cron job every 5 minutes
* Also accepts manual POST ingestion via `/admin/feed`
* Queried by Trenches endpoints for real-time token data
***
## Request Lifecycle
Hono matches the request path to a route handler. CORS headers are applied globally.
The middleware extracts the `X-PAYMENT` header, normalizes the network format, and forwards to the appropriate facilitator (Dexter for Solana, PayAI for Base/SKALE).
The handler checks Workers KV for a cached response. On cache hit, the cached response is returned immediately (skipping data fetch and LLM).
On cache miss, the handler fetches data from upstream sources (Solana RPC, Jupiter, Meteora, DeFiLlama, Nansen, etc.).
Raw data is sent to the LLM cascade for interpretation. The cascade tries models in priority order with 8-10s timeouts per model.
The `enrich()` function assembles the standard `HyreResponse` envelope: `{data, insight, signal, confidence, sources, model_used, latency_ms, timestamp}`.
The response is cached in Workers KV and returned to the client. The x402 middleware settles the payment via the facilitator.
***
## Deployment
| Property | Value |
| ------------------ | ------------------------------- |
| Platform | Cloudflare Workers |
| Regions | 300+ edge locations globally |
| Cold starts | Zero (V8 isolates) |
| Max execution time | 30 seconds (Workers limit) |
| Memory limit | 128 MB per isolate |
| Deploy command | `npm run deploy` (via Wrangler) |
| Custom domain | `mpp.hyreagent.fun` |
# Get Access
Source: https://docs.hyreagent.fun/gateway/get-access
Gateway API keys are issued manually to selected partners. Here's how to request one and what you get.
The HYRE LLM Gateway is **invite-only for integrations**. We don't do open self-serve signup for provider keys — every key is provisioned manually so we know who is on the other side, can size caps to your workload, and agree billing up front.
## Request an API key
DM [@Cryptoeights on X](https://x.com/Cryptoeights) or open an issue on [GitHub](https://github.com/Hyre-agent). Include:
* **Who you are** — project name, website, team contact
* **What you're building** — how HYRE fits as your LLM provider
* **Expected volume** — requests/day and rough token volume, which models you need
* **Billing preference** — prepaid credits or partner invoicing (below)
We review requests case by case. Agent platforms, DeFi products, and crypto-native apps are the best fit.
Approved partners receive a `hyre_gw_*` key over a private channel, along with the daily caps and billing terms configured for it.
## Key types
| | Standard key | Partner key |
| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------- |
| **Best for** | Single product using HYRE as its LLM backend | Platforms and marketplaces re-selling HYRE inference |
| **Billing** | Prepaid USDC credits (Solana), drawn per request | Unmetered at request time, invoiced out-of-band |
| **Daily caps** | 10,000 requests/day and \$50/day by default (customizable) | No metering caps |
| **Usage tracking** | Per-key daily usage counters | Full retail cost logged per request for invoicing |
## Limits and fair use
* Default caps are **10,000 requests/day** and **\$50 spend/day** per key. Hitting either returns `429` with a machine-readable `limit` object — see [Limits & Errors](/gateway/limits-and-errors).
* Caps are per key and reset at midnight UTC. Need more? Ask — caps are configurable per key.
* Keys can be revoked or rotated at any time. If your key leaks, contact us immediately for a rotation.
## Key security
* Treat `hyre_gw_*` keys like any provider secret: environment variables or a secret manager, never in client-side code or a public repo.
* The gateway stores only a SHA-256 hash of your key — we cannot recover a lost key, only rotate it.
Just want to use HYRE models yourself (not as a provider inside a product)? The [hyreagent.fun dashboard](https://hyreagent.fun) has self-serve PAYG with prepaid USDC credits, and the gateway accepts keyless [x402 per-call payments](/payment/x402-protocol).
# Limits & Errors
Source: https://docs.hyreagent.fun/gateway/limits-and-errors
Daily caps, the OpenAI-style error envelope, and every status code your integration should handle.
## Daily limits
Every metered key has two independent daily caps, reset at **midnight UTC**:
| Limit | Default | Behavior when hit |
| ---------------- | ------- | ---------------------------------------- |
| Requests per day | 10,000 | `429` with `code: "daily_request_limit"` |
| Spend per day | \$50.00 | `429` with `code: "daily_spend_limit"` |
Both are checked **before** the request runs, so a blocked request is never billed. Caps are configured per key — [ask us](/gateway/get-access) if your workload needs more. Partner (unmetered) keys have no daily caps.
Request size limits: at most **1,000 messages** per request, and `max_tokens` may not exceed the model's context length.
## Error envelope
Errors follow the OpenAI format, so existing SDK error handling works:
```json theme={null}
{
"error": {
"message": "Daily spend limit reached for this key",
"type": "rate_limit_error",
"code": "daily_spend_limit"
},
"limit": { "type": "spend", "cap": 50000000 }
}
```
The extra `limit` object appears only on `429` responses — `cap` is the configured cap (requests, or spend in micro-USD).
## Status codes
| Status | Type | When |
| ------ | ------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `400` | `invalid_request_error` | Malformed JSON, unknown model, invalid parameters |
| `401` | `authentication_error` / `invalid_api_key` | Missing, invalid, or revoked key |
| `402` | payment required | No key and no valid x402 payment — response carries the payment challenge |
| `429` | `rate_limit_error` | Daily request or spend cap reached (see above) |
| `5xx` | `server_error` / upstream | Upstream model failure or gateway error — any reserved hold is released, nothing is billed |
## Handling failures
* **Retries:** `5xx` responses are safe to retry — failed calls are never charged. Use exponential backoff; don't retry `400`/`401`.
* **`429`:** back off until midnight UTC or switch to a cheaper model; the `limit` object tells you which cap you hit.
* **Support:** every response includes an `X-Request-Id` header. Include it in any report — we can trace the exact request.
## Insufficient credits
When a metered key's prepaid balance can't cover a request's reserve, the request is rejected before running. Top-up terms are part of your access agreement — contact us to add credits or review your invoice schedule.
# Models & Pricing
Source: https://docs.hyreagent.fun/gateway/models
20+ models behind one endpoint — open-weight and frontier — with transparent, live-synced pricing.
## Live catalog
The source of truth is the public catalog endpoint — no auth required:
```bash theme={null}
curl https://gw.hyreagent.fun/api/inference/v1/models
```
Each entry includes the model id, tier, context length, live per-1M-token pricing (human-readable and micro-USD integers), whether it's today's free-tier model, and any active promo:
```json theme={null}
{
"id": "zai-org/GLM-5",
"name": "GLM 5",
"tier": "STANDARD",
"provider": "deepinfra",
"context_length": 202752,
"free_eligible": false,
"pricing": {
"input_per_1m": "$0.72",
"output_per_1m": "$2.496",
"input_per_1m_micro": 720000,
"output_per_1m_micro": 2496000
}
}
```
Prices are synced from upstream daily and can carry limited-time promo discounts, so always read live pricing from `GET /models` rather than hardcoding it. Docs tables below list the lineup, not prices.
## Model lineup
### Open-weight models
Served via DeepInfra. Tiers by retail output price: **FLASH** (under \$0.60/M), **STANDARD** (under \$3/M), **PREMIUM** (\$3/M and above).
| Model id | Name | Tier | Context |
| --------------------------------------------------- | --------------------- | -------- | ------- |
| `deepseek-ai/DeepSeek-V4-Flash` | DeepSeek V4 Flash | FLASH | 1M |
| `zai-org/GLM-4.7-Flash` | GLM 4.7 Flash | FLASH | 200K |
| `stepfun-ai/Step-3.5-Flash` | Step 3.5 Flash | FLASH | 262K |
| `google/gemma-4-31B-it` | Gemma 4 31B | FLASH | 262K |
| `zai-org/GLM-5` | GLM 5 | STANDARD | 200K |
| `Qwen/Qwen3.5-397B-A17B` | Qwen 3.5 397B | STANDARD | 262K |
| `meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | Llama 4 Maverick | STANDARD | 1M |
| `MiniMaxAI/MiniMax-M2.7` | MiniMax M2.7 | STANDARD | 196K |
| `nvidia/NVIDIA-Nemotron-3-Super-120B-A12B` | Nemotron 3 Super 120B | STANDARD | 262K |
| `deepseek-ai/DeepSeek-V4-Pro` | DeepSeek V4 Pro | PREMIUM | 1M |
| `moonshotai/Kimi-K2.6` | Kimi K2.6 | PREMIUM | 262K |
| `moonshotai/Kimi-K2.7-Code` | Kimi K2.7 | PREMIUM | 262K |
| `zai-org/GLM-5.2` | GLM 5.2 | PREMIUM | 1M |
### Frontier models
Proprietary frontier models served through HYRE's compute partners — same endpoint, same key. All PREMIUM tier.
| Model id | Name | Context |
| ------------------------------- | ----------------- | ------- |
| `anthropic-claude-opus-4-8` | Claude Opus 4.8 | 1M |
| `anthropic-claude-sonnet-4-6` | Claude Sonnet 4.6 | 1M |
| `openai-gpt-55` | GPT-5.5 | 1M |
| `openai-gpt-54` | GPT-5.4 | 1M |
| `openai-gpt-54-mini` | GPT-5.4 Mini | 400K |
| `google-gemini-3-1-pro-preview` | Gemini 3.1 Pro | 1M |
| `google-gemini-3-flash-preview` | Gemini 3 Flash | 256K |
| `x-ai-grok-4-3` | Grok 4.3 | 1M |
## How pricing works
* **Retail = live upstream price × 1.20.** No hidden margins, no per-seat fees — you pay a flat 20% markup over the provider rate for routing, billing, and support.
* Billing is **per token** (input and output priced separately), computed from the usage the upstream reports. Streaming responses bill from the final usage frame.
* Metered keys **reserve against your balance before the call and settle to actual usage after** — you're never charged more than the tokens you consumed.
* **Promos** (limited-time discounts, holder free tiers) apply automatically and are visible in `GET /models` while active — no code changes needed on your side.
## Free daily model
One FLASH/STANDARD model is hand-picked as free each UTC day (`free_eligible: true` in `/models`), with a per-user quota for eligible \$HYRE holders. Treat it as a bonus, not capacity to build against.
# LLM Gateway Overview
Source: https://docs.hyreagent.fun/gateway/overview
Use HYRE as the LLM provider inside your own product — one OpenAI-compatible endpoint, 20+ models, crypto-native billing.
The HYRE LLM Gateway is an OpenAI-compatible inference API. If your app, agent, or platform already talks to OpenAI, you can switch to HYRE by changing two lines: the base URL and the API key.
```
Base URL https://gw.hyreagent.fun/api/inference/v1
Auth Authorization: Bearer hyre_gw_...
```
Gateway API keys are **not self-serve for integrations**. Access is granted to selected partners — [request an API key](/gateway/get-access) before you start building.
## Why route through HYRE
Open-weight models (DeepSeek, GLM, Llama, Qwen, Kimi, MiniMax) plus frontier models (Claude, GPT, Gemini, Grok) behind a single endpoint.
`/chat/completions` and `/models` follow the OpenAI schema — the OpenAI SDK, LangChain, and the Vercel AI SDK work unchanged.
Prepaid USDC credits, per-call x402 micropayments, or partner invoicing. No card on file, no subscription.
SSE streaming with usage reporting, function calling (`tools` / `tool_choice`), and `response_format` all pass through.
## How access works
Tell us who you are and what you're building — see [Get Access](/gateway/get-access). Access is selective; we issue keys manually.
You get a `hyre_gw_*` key with agreed daily caps and billing terms (prepaid credits or partner invoicing).
Set the base URL and key in your OpenAI client. Done — see the [Quickstart](/gateway/quickstart).
## Endpoints
| Method | Path | Auth | Description |
| ------ | ------------------------------------ | --------------- | -------------------------------------------------------------- |
| `POST` | `/api/inference/v1/chat/completions` | API key or x402 | OpenAI-compatible chat completions (streaming + non-streaming) |
| `GET` | `/api/inference/v1/models` | none | Public model catalog with live pricing and free-tier flags |
No API key? The gateway also accepts per-call [x402 payments](/payment/x402-protocol) (Solana USDC or BSC USD1/USDT/USDC) — a `402` challenge is returned and your wallet or agent pays per request. Keys are the right choice for production integrations; x402 is great for agents paying as they go.
# Gateway Quickstart
Source: https://docs.hyreagent.fun/gateway/quickstart
Point your existing OpenAI client at HYRE — two lines of config, no other code changes.
Everything below assumes you already have a `hyre_gw_*` key — if not, [request access](/gateway/get-access) first.
## Base configuration
```
Base URL: https://gw.hyreagent.fun/api/inference/v1
API key: hyre_gw_... (sent as a Bearer token)
```
## Make a request
```bash theme={null}
curl https://gw.hyreagent.fun/api/inference/v1/chat/completions \
-H "Authorization: Bearer $HYRE_GATEWAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-ai/DeepSeek-V4-Flash",
"messages": [
{ "role": "user", "content": "Explain impermanent loss in one paragraph." }
],
"max_tokens": 300
}'
```
```python theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://gw.hyreagent.fun/api/inference/v1",
api_key=os.environ["HYRE_GATEWAY_KEY"], # hyre_gw_...
)
response = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V4-Flash",
messages=[
{"role": "user", "content": "Explain impermanent loss in one paragraph."}
],
max_tokens=300,
)
print(response.choices[0].message.content)
```
```typescript theme={null}
import OpenAI from 'openai'
const client = new OpenAI({
baseURL: 'https://gw.hyreagent.fun/api/inference/v1',
apiKey: process.env.HYRE_GATEWAY_KEY, // hyre_gw_...
})
const response = await client.chat.completions.create({
model: 'deepseek-ai/DeepSeek-V4-Flash',
messages: [
{ role: 'user', content: 'Explain impermanent loss in one paragraph.' },
],
max_tokens: 300,
})
console.log(response.choices[0].message.content)
```
```typescript theme={null}
import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
import { generateText } from 'ai'
const hyre = createOpenAICompatible({
name: 'hyre',
baseURL: 'https://gw.hyreagent.fun/api/inference/v1',
apiKey: process.env.HYRE_GATEWAY_KEY,
})
const { text } = await generateText({
model: hyre('deepseek-ai/DeepSeek-V4-Flash'),
prompt: 'Explain impermanent loss in one paragraph.',
})
```
```python theme={null}
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="https://gw.hyreagent.fun/api/inference/v1",
api_key=os.environ["HYRE_GATEWAY_KEY"],
model="deepseek-ai/DeepSeek-V4-Flash",
)
print(llm.invoke("Explain impermanent loss in one paragraph.").content)
```
## Streaming
Set `"stream": true` — the gateway streams standard OpenAI SSE chunks, including a final usage frame, so SDK streaming helpers work unchanged:
```python theme={null}
stream = client.chat.completions.create(
model="zai-org/GLM-5",
messages=[{"role": "user", "content": "Write a haiku about Solana."}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")
```
## Supported parameters
The request schema follows OpenAI's `/chat/completions`:
| Parameter | Notes |
| -------------------------------------- | ------------------------------------------------------------- |
| `model` | Required — a catalog id from [`GET /models`](/gateway/models) |
| `messages` | Required — up to 1,000 messages |
| `max_tokens` / `max_completion_tokens` | Positive integer, capped at the model's context length |
| `temperature` | `0` – `2` |
| `top_p` | `0` – `1` |
| `stop` | String or array of strings |
| `stream` | Boolean — SSE streaming |
| `tools`, `tool_choice` | Function calling, passed through to the model |
| `response_format` | e.g. JSON mode, passed through to the model |
Every response carries an `X-Request-Id` header — include it when reporting an issue.
## Next steps
20+ models across FLASH, STANDARD, and PREMIUM tiers with live pricing.
Daily caps, error envelope, and status codes to handle in production.
# Welcome to HYRE
Source: https://docs.hyreagent.fun/introduction
AI-powered DeFi intelligence. Pay per query via x402 — no API keys, no subscriptions.
HYRE is a DeFi data API that returns AI-interpreted insights with every response. 22 endpoints across 6 segments, powered by Gemini 2.5 Flash on Cloudflare Workers.
Payment is the only gate. No API keys needed — every endpoint is paid via the [x402 protocol](/payment/x402-protocol) on Solana, Base, or SKALE.
## Get Started
Make your first paid API call in under 2 minutes.
Chat with HYRE via our web interface — sign in with Privy, no wallet setup.
Use HYRE as the LLM provider in your own product — OpenAI-compatible, 20+ models, one key.
## Explore Endpoints
PumpFun launches, bonding curves, token verdicts, sniper detection.
Wallet PnL, positions, top wallets, whale tracking, OHLCV.
Meteora DLMM pools, AI recommendations, position rebalancing.
Cross-chain TVL snapshots and yield opportunities.
Nansen-powered flow intelligence, token screening, wallet profiling.
Natural language meta-endpoint — HYRE routes your question to the right tool.
## How It Works
POST to any endpoint with your data query. No authentication headers needed.
The endpoint returns `402 Payment Required` with pricing. Your agent or wallet signs the payment automatically.
Receive structured data + LLM-interpreted insight, signal, and confidence score in a single response.
## Standard Response
Every paid endpoint returns this envelope:
```json theme={null}
{
"data": { ... },
"insight": "SOL-USDC pool on Meteora offers 40% APR with deep liquidity...",
"signal": "add_liquidity",
"confidence": 0.85,
"sources": ["meteora-dlmm"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 2100,
"timestamp": "2026-04-17T00:00:00Z"
}
```
Prefer a chat interface? Try the [Agent Playground](https://hyreagent.fun/chat) — sign in with email, get a custodial wallet, and start chatting. No wallet setup required.
# API reference
Source: https://docs.hyreagent.fun/me/api-reference
REST endpoints exposed at me.hyreagent.fun for reading agent state.
`me.hyreagent.fun` is the canonical read surface for every ME passport. These endpoints are free and read-only.
For writes (mint, edit, transfer) use the [claim flow](https://me.hyreagent.fun/claim), the [BYOA registration](https://me.hyreagent.fun/register-existing), or the [SDK](/me/sdk) — all sign transactions via the owner's Solana wallet.
## `GET /manifest/:name`
Fetch an agent's current ERC-8004 manifest — services, capabilities (picked skills as `:` ids), tags, and registrations.
```bash theme={null}
curl https://me.hyreagent.fun/manifest/alice
```
**Response** — see [Manifest spec](/me/manifest-spec) for the full shape.
## `GET /api/agents`
List registered agents (KV-backed registry, newest first).
```bash theme={null}
curl "https://me.hyreagent.fun/api/agents?limit=50"
```
```json theme={null}
{
"agents": [
{
"name": "alice",
"assetAddress": "5yLA…Pr52",
"ownerWallet": "7G73…yGgC",
"description": "Crypto trading assistant",
"createdAt": 1751846400000
}
]
}
```
BYOA passports additionally carry `"kind": "byoa"` and `"displayName"` (the agent's original-casing name — its Core asset has no `.me` suffix).
## `GET /api/agents/:name/exists`
Authoritative availability check — one namespace shared by native `.me` names and BYOA slugs.
```bash theme={null}
curl https://me.hyreagent.fun/api/agents/alice/exists
```
```json theme={null}
{
"name": "alice",
"normalized": "alice",
"exists": true,
"available": false,
"source": "registry",
"record": { "name": "alice", "ownerWallet": "7G73…yGgC" }
}
```
## `GET /api/agent/primary-alias/:name`
Resolve an agent's display fields — bare `displayName`, `.me` `passportHandle`, and the locked-in `.sol` alias when the agent has upgraded.
```bash theme={null}
curl https://me.hyreagent.fun/api/agent/primary-alias/alice
```
```json theme={null}
{
"name": "alice",
"displayName": "alice",
"passportHandle": "alice.me",
"displayHandle": "alice.me",
"primarySol": null,
"source": "chain"
}
```
## `GET /api/said-card/:name`
SAID Protocol identity card JSON (the `metadataUri` embedded at SAID registration). Public and unauthenticated so indexers can read it freely.
```bash theme={null}
curl https://me.hyreagent.fun/api/said-card/alice
```
## Skill catalog
The tool catalog that powers the claim-time skill browser (and resolves manifest `capabilities` ids) is served at:
```bash theme={null}
curl https://me.hyreagent.fun/api/skills
```
Each capability id in a manifest is `:` against this catalog — e.g. `token-intel:whales`, `agentcash-travel:amadeus-flights`.
# ME CLI
Source: https://docs.hyreagent.fun/me/cli
The `me` command wraps Metaplex Agents primitives — mint agents, launch tokens, edit manifests, all in one CLI.
`me` is a zero-dependency CLI that wraps `@metaplex-foundation/mpl-agent-registry` with ME Protocol's naming convention and manifest mirror.
## Install
```bash theme={null}
npm i -g @me-protocol/cli
```
Or use without installing:
```bash theme={null}
npx @me-protocol/cli claim toly
```
## Commands
### `me claim `
Mint a new agent via Metaplex Agents. Creates Core NFT + Agent Identity PDA + Asset Signer PDA + publishes manifest.
```bash theme={null}
me claim toly --template trench-hunter
```
The `.me` handle. 2+ chars, lowercase, unclaimed — every name is free.
Template ID (`trench-hunter`, `lp-strategist`, `defi-yield`, etc.). Seeds capabilities.
External endpoint URL for BYO flow. Mutually exclusive with `--template`.
One-liner shown on profile + in MCP manifest.
Comma-separated, max 6 (e.g. `defi,mcp,solana`).
### `me launch-token `
Launch an agent token via Metaplex Genesis bonding curve. Creator fees route 100% to the agent's Asset Signer PDA. One-token-per-agent (`setToken=true` locked).
```bash theme={null}
me launch-token alice \
--symbol ALICE \
--supply 2400000 \
--first-buy 0.5
```
The agent `.me` handle.
Token symbol (2-10 chars). Auto-prefixed with `$`.
Fixed total supply.
Optional reserved first-buy in SOL. Routed through agent PDA, fees waived.
Local path to token image. Uploaded to Irys automatically.
### `me edit `
Update profile (avatar, description, tags, capabilities, tiers). Opens inline editor.
```bash theme={null}
me edit toly
```
### `me transfer `
Transfer the `.me` Core NFT to another Solana wallet. Asset Signer PDA control transfers atomically.
```bash theme={null}
me transfer toly 9Nx2...bQr4
```
### `me resolve `
Fetch and print the current ERC-8004 manifest.
```bash theme={null}
me resolve alice
```
### `me verify `
Trigger ownership verification for the endpoint.
```bash theme={null}
me verify alice --method wallet-sign
me verify alice --method well-known
```
## Example sessions
```bash Mint + launch token in one flow theme={null}
$ me claim toly --template trench-hunter --description "Solana trading bot"
→ mintAndSubmitAgent (Metaplex Agents)... ok
→ derive Asset Signer PDA... 8Mz4...tPw2
→ upload ERC-8004 manifest to R2... ok
→ publish MCP + A2A services... ok
→ index to solana:101:metaplex registry... ok
> toly.me is live
$ me launch-token toly --symbol TOLY --supply 1000000 --first-buy 1.0
→ registerIdentityV1 on Core asset... ok
→ createAndRegisterLaunch via Genesis... ok
→ lock setToken=true (permanent pair)... ok
→ publish updated manifest... ok
> $TOLY is trading · bonding curve live
```
```bash BYO existing agent theme={null}
$ me claim boba \
--endpoint https://api.boba.dev \
--description "Trading bot on Solana" \
--tags trading,mcp
→ probing endpoint... 4 capabilities found
→ mintAndSubmitAgent (Metaplex Agents)... ok
→ publish MCP manifest... ok
> boba.me → https://api.boba.dev
```
## Environment
| Variable | Default | Purpose |
| --------------------- | ------------------------------------ | ------------------------------------ |
| `SOLANA_RPC_URL` | public mainnet | RPC used for mint + read calls |
| `SOLANA_KEYPAIR` | `~/.config/solana/id.json` | Wallet funding the mint |
| `ME_API_URL` | `https://me.hyreagent.fun/api` | Override for self-hosted deployments |
| `METAPLEX_AGENTS_API` | `https://api.metaplex.com/v1/agents` | Override Metaplex endpoint |
## Relationship to Metaplex Agents
`me` CLI delegates to Metaplex Agents for every on-chain primitive:
| CLI command | Metaplex Agents function |
| ----------------- | ------------------------------------------------ |
| `me claim` | `mintAndSubmitAgent` |
| `me launch-token` | `registerIdentityV1` + `createAndRegisterLaunch` |
| `me transfer` | Core asset transfer (standard) |
| `me resolve` | DAS API + manifest mirror |
| `me verify` | ME-specific extension |
For programmatic usage, see the [TypeScript SDK](/me/sdk).
# Manifest spec
Source: https://docs.hyreagent.fun/me/manifest-spec
ERC-8004 compliant agent registration document, as published by Metaplex Agents and mirrored at me.hyreagent.fun/manifest/.
Every minted `.me` publishes a signed registration document following the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) standard. The same document is indexed on-chain via Metaplex Agents' identity PDA and mirrored off-chain at `me.hyreagent.fun/manifest/` for fast consumer lookups.
## Example
```json me.hyreagent.fun/manifest/alice theme={null}
{
"$schema": "https://eips.ethereum.org/EIPS/eip-8004",
"type": "agent",
"name": "alice.me",
"description": "Crypto trading assistant",
"wallet": "4B9x...kPm3",
"services": [
{
"name": "mcp",
"endpoint": "https://me.hyreagent.fun/manifest/alice",
"version": "2025-06-18"
},
{
"name": "web",
"endpoint": "https://agents.me/alice"
},
{
"name": "A2A",
"endpoint": "https://agents.me/alice/a2a",
"version": "0.3.0"
}
],
"registrations": [
{ "registry": "solana:101:metaplex", "id": "9Xz...aBc" }
],
"supportedTrust": [],
"x402Support": true,
"capabilities": [
{
"method": "get",
"path": "/trenches/new-tokens",
"price_micro_usd": 2000,
"tier_required": { "token": "8Rv...bQ1", "min_balance": 0 }
},
{
"method": "get",
"path": "/trenches/verdict/:token",
"price_micro_usd": 10000,
"tier_required": { "token": "8Rv...bQ1", "min_balance": 100000 }
}
]
}
```
## Standard fields (ERC-8004)
Always `https://eips.ethereum.org/EIPS/eip-8004`.
Always `agent` for ME Protocol.
The fully-qualified `.me` handle (e.g. `alice.me`).
Human-readable one-liner. 280 chars max. Shown in registries and MCP clients.
Agent's Asset Signer PDA, derived from `['mpl-core-execute', ]`. Receives payments and creator fees.
Service endpoints the agent exposes. Each entry has `name` (mcp / web / A2A), `endpoint` (URL), and optional `version`.
On-chain registry entries. ME agents always include `{ registry: "solana:101:metaplex", id: }`.
Array of trust models the agent accepts (empty by default; extensible).
## ME Protocol extensions
Fields beyond the ERC-8004 base. Opt-in, parsed by ME-aware clients only.
Whether endpoint speaks [x402](/payment/x402-protocol) natively. If `true`, consumers can pay per call without a custom payment handshake.
Paid endpoints with per-method pricing in micro-USD.
HTTP method, lowercase: `get` | `post` | `put` | `delete` | `patch`.
Endpoint path, resolved against the agent's `services[0].endpoint`.
Cost per call in micro-USD. `0` = free.
Optional ME-specific tier gate. When set, consumers must hold `min_balance` of the named token to call. Enforced off-chain via Solana RPC balance check at paywall time.
## On-chain anchoring
The off-chain JSON is mirrored on-chain through Metaplex Agents:
1. **Metaplex Core Asset** (NFT) holds the agent's identity. The `uri` field points back to `me.hyreagent.fun/manifest/`.
2. **Agent Identity PDA** (from `registerIdentityV1`) attaches the ERC-8004 document to the Core asset with lifecycle hooks for Transfer, Update, and Execute.
3. **Asset Signer PDA** (`['mpl-core-execute', ]`) is the agent's wallet. Derived deterministically from the mint — no separate keypair to manage.
## Verifying ownership
```typescript theme={null}
import { fetchAgentByName } from "@metaplex-foundation/mpl-agent-registry";
const agent = await fetchAgentByName(umi, "alice.me");
assert(agent.owner === currentClaimedOwner); // NFT ownership check
assert(agent.assetSigner === manifest.wallet); // wallet binding check
```
The manifest tells you what the agent *claims* to do. The on-chain Core asset tells you who *owns* it. Metaplex guarantees they stay in sync — transferring the Core NFT automatically transfers control of the Asset Signer PDA.
## Custom attributes
Extend manifests via Metaplex Core's Attributes plugin for extra fields like `image`, `tags`, or `token_mint`. These are surfaced on the [agent profile page](https://me.hyreagent.fun) and appear in MCP client UIs that support rich metadata.
```json Extended manifest (with token) theme={null}
{
"$schema": "https://eips.ethereum.org/EIPS/eip-8004",
"name": "alice.me",
"attributes": {
"image": "https://r2.me.hyreagent.fun/alice/avatar.png",
"tags": ["hyre-trenches", "jupiter-swap", "mcp"],
"token_mint": "8Rv...bQ1"
},
"services": [...],
"capabilities": [...]
}
```
When `attributes.token_mint` is present, the agent has an associated token launched via [Metaplex Genesis](/me/cli#token-launch). The token is permanently paired with the agent via `setToken=true`.
# MCP integration
Source: https://docs.hyreagent.fun/me/mcp-integration
How Claude Desktop, Cursor, and any MCP-compatible client consumes .me agents.
Every minted `.me` publishes a [Model Context Protocol](https://modelcontextprotocol.io) manifest at `me.hyreagent.fun/manifest/`. Add that URL to any MCP-compatible client and the agent's capabilities show up as callable tools.
## Claude Desktop
Edit your `claude_desktop_config.json`:
```json claude_desktop_config.json theme={null}
{
"mcpServers": {
"alice-me": {
"url": "https://me.hyreagent.fun/manifest/alice"
}
}
}
```
Restart Claude Desktop. All of `alice.me`'s capabilities show up as tools and Claude can call them directly — payment is handled via your configured wallet (Phantom, Solflare, or any browser extension with x402 support).
## Cursor
Paste the manifest URL into **Settings → Features → Model Context Protocol → Add server**:
```
https://me.hyreagent.fun/manifest/alice
```
Cursor handles the same flow as Claude Desktop.
## Any MCP client
The manifest follows the standard MCP schema — just point any MCP-compatible client at the URL.
## Paywall flow
When an MCP client calls a paid capability, the flow is:
Client hits `https://agents.me/alice/trenches/new-tokens`.
Response includes an x402 challenge with price and payment networks.
User-configured wallet signs a USDC transfer on Solana/Base/Tempo.
On payment confirmation, endpoint returns the actual data + receipt.
No API keys. No rate limits. No account management. Just pay per call.
## Advertising as a .me agent
If you're building an MCP server and want to advertise it via `.me`, [mint the name](https://me.hyreagent.fun/register-existing) and point it at your existing endpoint. The manifest auto-publishes and you're discoverable by every MCP client.
```bash theme={null}
# CLI path
me claim myagent \
--endpoint https://api.myagent.com \
--description "My awesome MCP agent" \
--tags mcp,search,web
```
See the [BYO flow](https://me.hyreagent.fun/register-existing) for the UI path.
## Endpoint requirements
For MCP consumers to use your `.me` smoothly:
* **Public https endpoint** with valid TLS cert
* **x402-compatible** or exposes free-tier routes for discovery
* **Stable API surface** — capability paths are published on-chain, so breaking them breaks downstream consumers
* **CORS enabled** if browser MCP clients are expected
See [ownership verification](/me/manifest-spec#verifying-ownership) for how consumers confirm a manifest matches the on-chain NFT.
# ME Protocol
Source: https://docs.hyreagent.fun/me/overview
The discovery + UX layer on top of Metaplex Agents. Claim a .me identity, launch a Genesis token, publish via MCP — all infra flexible and open.
ME Protocol is the **discovery + UX layer on top of [Metaplex Agents](https://www.metaplex.com/docs/agents)**. Every `.me` agent is a Metaplex Core NFT with a registered Agent Identity PDA, an Asset Signer wallet, and optionally a Genesis-launched token — all standard primitives owned by Metaplex, not us.
What ME adds: a **human-readable naming namespace**, a **manifest registry** at `me.hyreagent.fun/manifest/`, **HYRE-powered skill catalog**, **x402 paywall with tier gating**, and a **registry UI** at me.hyreagent.fun.
Pricing is single-line: **every name is free — any length**. You pay only the on-chain mint cost from your own wallet (\~0.01 SOL Core-asset rent + fees, one signature). No renewals, no premium tiers, no token holdings required, no creator cut. Creator fees on your agent token route 100% to you.
## Two-layer architecture
Core NFT identity, Agent Identity PDA, Asset Signer wallet, Genesis bonding curve token launch, ERC-8004 registration format. Owned and maintained by Metaplex.
`.me` naming, manifest registry, skill catalog, x402 paywall, tier gating, discovery UI. Owned by ME.
If ME goes away, your agent's Core NFT and token survive unchanged. Any Metaplex-aware client (Claude, Cursor, or custom MCP consumers) can still read and call your agent.
## Three pillars
Every `.me` is a Metaplex Core asset with an Agent Identity PDA. Transfer, sell, delegate — behaves like any other Solana NFT.
Keyless wallet bound to the NFT via `['mpl-core-execute', ]` PDA. Receives payments and creator fees automatically.
Launch a Genesis-curve token. Holders unlock premium endpoints via ME's x402 tier extension. Creator fees 100% to you.
## Get started
Pick any name, 2+ characters — every name is free. One wallet signature; you pay only the mint (\~0.01 SOL). Pick skills at claim time and they're advertised as MCP services in your passport.
Already running an agent? Register a passport-only identity — Core NFT named after your agent verbatim (no `.me` suffix), ERC-8004 registration, and a discovery listing. Your agent keeps its own name.
## How it works
Your wallet signs one Metaplex mint transaction (you pay \~0.01 SOL rent + fees). Creates a Core NFT, registers the Agent Identity PDA, derives the Asset Signer wallet — all in one atomic transaction.
Pick skills from the HYRE catalog or paste your own endpoint URL. ME publishes the ERC-8004 manifest to `me.hyreagent.fun/manifest/` — picked skills appear as `capabilities` and an `mcp` service.
Call `createAndRegisterLaunch` via Metaplex Genesis. Bonding curve deployed, `setToken=true` locks permanent pairing, creator fees route 100% to your Asset Signer PDA.
Set per-endpoint `tier_required` in manifest. ME's x402 middleware checks holder balance at paywall time via RPC.
Charge per call via x402 (USDC). Earn creator fees on every token trade. Holders with premium tier unlock gated endpoints.
## Deep dives
ERC-8004 registration document. Services, capabilities, tier gates.
`me` command wrapping Metaplex Agents primitives.
`@me-protocol/sdk` on top of `@metaplex-foundation/mpl-agent-registry`.
How Claude Desktop and Cursor consume `.me` agents.
REST endpoints at me.hyreagent.fun.
Template-powered endpoints on HYRE's x402 rails.
## Why ME vs. raw Metaplex Agents?
You can skip ME entirely and use Metaplex Agents directly. You'll get identity, wallet, and token launch. What you won't get: a `.me` naming convention, a curated template catalog, x402 paywall + tier gating, an agent registry UI, or social share assets.
ME is for builders who want to ship an agent in 3 minutes instead of 3 weeks. You can always eject to raw Metaplex later — your Core NFT and token are standard primitives.
## Why not SNS or ENS?
SNS and ENS are naming services. ME is an **identity + commerce layer** for agents. The name is the entry point; what makes it valuable is the bundle: a Metaplex Agents-registered identity, a keyless Asset Signer wallet, an MCP manifest consumers can discover, and pay-per-call rails with holder-tier gating. SNS and ENS give you a name. ME gives you a citizen.
See the [comparison table](https://me.hyreagent.fun#vs) on the landing page for the full breakdown.
# TypeScript SDK
Source: https://docs.hyreagent.fun/me/sdk
@me-protocol/sdk — wraps @metaplex-foundation/mpl-agent-registry with ME-specific naming, manifest mirror, and x402 tier gating.
`@me-protocol/sdk` is a thin layer over Metaplex's agent SDK. It keeps the Metaplex primitives (mint, register, Genesis token launch) while adding ME's naming convention, manifest registry at `me.hyreagent.fun/manifest`, and tier-gated x402 payment handling.
## Install
```bash theme={null}
npm i @me-protocol/sdk @metaplex-foundation/mpl-agent-registry @metaplex-foundation/umi-bundle-defaults
```
## Quickstart
```typescript app.ts theme={null}
import { Me } from "@me-protocol/sdk";
import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { mplAgentIdentity } from "@metaplex-foundation/mpl-agent-registry";
const umi = createUmi("https://api.mainnet-beta.solana.com").use(mplAgentIdentity());
const me = new Me({ umi });
// Resolve a .me via DAS + manifest mirror
const alice = await me.resolve("alice.me");
console.log(alice.services.find((s) => s.name === "mcp")?.endpoint);
// Call a paid + tier-gated endpoint — SDK handles x402 + balance check
const res = await me.call(alice, "/trenches/verdict/$BONK", {
maxAmount: 0.01,
});
// Check ownership
const isOwner = await me.isOwner("alice.me", myWallet.publicKey);
```
## Minting a new agent
Delegates to Metaplex's `mintAndSubmitAgent`. The `.me` naming convention is enforced client-side; on-chain the asset just carries the string.
```typescript theme={null}
const result = await me.claim({
name: "toly", // auto-suffixed to toly.me
description: "My new agent",
services: [
{ name: "web", endpoint: "https://toly.ai" },
{ name: "mcp", endpoint: "https://me.hyreagent.fun/manifest/toly", version: "2025-06-18" },
],
});
console.log(result.assetAddress); // Metaplex Core NFT mint
console.log(result.assetSigner); // agent wallet PDA
console.log(result.manifestUrl); // me.hyreagent.fun/manifest/toly
```
## Launching an agent token
Uses Metaplex Genesis protocol via `createAndRegisterLaunch`. Creator fees auto-route 100% to the agent's Asset Signer PDA. ME takes zero cut.
```typescript theme={null}
const launch = await me.launchToken("alice.me", {
symbol: "ALICE", // auto-prefixed to $ALICE
supply: 2_400_000,
image: "https://r2.me.hyreagent.fun/alice/token.png", // will be uploaded to Irys
firstBuySol: 0.5, // optional reserved first-buy
tiers: [
{ label: "Basic", minBalance: 1_000, unlocks: ["/read/*"] },
{ label: "Pro", minBalance: 100_000, unlocks: ["/write/*"] },
],
});
console.log(launch.mint); // $ALICE SPL token mint
console.log(launch.curvePda); // Genesis bonding curve state
```
`setToken=true` is locked automatically. An agent can only ever launch one token — this pairing is permanent.
## Calling tier-gated endpoints
The SDK reads `capabilities[].tier_required` from the manifest and pre-checks the caller's balance before committing payment — better UX than failing after the USDC is spent.
```typescript theme={null}
try {
const res = await me.call(alice, "/trenches/verdict/X", { maxAmount: 0.01 });
} catch (err) {
if (err.code === "insufficient_tier") {
console.log(`Need ${err.required} ${err.symbol}. You have ${err.balance}.`);
console.log(`Buy more: ${err.upgradeUrl}`);
}
}
```
## API reference
### `new Me(opts)`
Umi instance with `mplAgentIdentity()` plugin.
Override the default `https://me.hyreagent.fun/manifest` registry. Use for staging / testnet.
### `me.resolve(name)`
Fetch the manifest for a `.me` via DAS API + manifest mirror. Returns the full ERC-8004 document. See [Manifest spec](/me/manifest-spec).
### `me.claim(opts)`
Calls Metaplex's `mintAndSubmitAgent`. Returns `{ assetAddress, assetSigner, manifestUrl }`.
### `me.launchToken(name, opts)`
Calls Metaplex Genesis `createAndRegisterLaunch`. Returns `{ mint, curvePda }`. Creator fees route to `assetSigner`.
### `me.call(manifest, path, opts)`
Executes a paid API call. Handles x402 challenge, tier check (balance RPC), payment signing.
### `me.isOwner(name, wallet)`
Returns `true` if the given wallet currently owns the `.me` Core asset.
### `me.assetSigner(name)`
Returns the Asset Signer PDA address. Derived deterministically from the agent's mint via `['mpl-core-execute', ]`.
## Runtime support
| Runtime | Status |
| ------------------ | ----------------------------------------------------- |
| Node 18+ | Full support |
| Deno / Bun | Full support |
| Cloudflare Workers | Full support (edge runtime) |
| Browser | Resolve + call — needs wallet adapter for mint/launch |
## Relationship to Metaplex Agents
| Feature | Metaplex Agents | ME Protocol SDK |
| ----------------- | ------------------------- | --------------------------------------------- |
| Mint identity | `mintAndSubmitAgent` | `me.claim()` — wraps it |
| Register identity | `registerIdentityV1` | auto-called in `me.claim()` |
| Launch token | `createAndRegisterLaunch` | `me.launchToken()` — wraps it |
| Name resolution | Asset address / DAS | `me.resolve("alice.me")` — wraps DAS + mirror |
| Tier-gated calls | — | `me.call()` — ME extension |
| x402 payment | — | handled in `me.call()` |
ME Protocol SDK is always compatible with the underlying Metaplex primitives. If ME goes away tomorrow, your agent's Core NFT and token survive — and any Metaplex-aware client can still read the registration doc.
# Escrow vs On-Chain
Source: https://docs.hyreagent.fun/payment/escrow-vs-onchain
Compare the Playground escrow mode with direct x402 agent-to-agent payments.
# Escrow vs On-Chain Payment
HYRE supports two payment modes. Choose based on your use case.
***
## Comparison
| Feature | Playground Escrow | Direct x402 |
| -------------------- | ----------------------------------- | ---------------------------------------------- |
| **Auth** | Privy (email/social login) | Wallet signature |
| **Wallet** | Custodial (managed by HYRE) | Self-custody |
| **Payment flow** | Deposit once, auto-deduct per query | Sign payment per request |
| **Signing** | Automatic (no popups) | Client-side wallet signing |
| **Supported chains** | Solana, Base, SKALE | Solana, Base, SKALE |
| **Gas fees** | Absorbed by HYRE | Solana: sponsored / Base: caller / SKALE: free |
| **Settlement** | Internal ledger (batched on-chain) | Per-request on-chain |
| **Minimum deposit** | None | None |
| **Withdrawal** | Anytime to any wallet | N/A (self-custody) |
| **Best for** | Human researchers, exploration | Bots, agents, automation |
| **Interface** | Chat UI at hyreagent.fun | HTTP API |
***
## When to Use Escrow
You want to explore HYRE's endpoints interactively without setting up wallet tooling. Sign in with email, deposit \$5 of USDC, and start chatting.
You don't have a crypto wallet and don't want to manage private keys. Privy handles wallet creation transparently.
You want to test endpoints and see response formats before building an integration.
***
## When to Use Direct x402
Your bot or AI agent calls HYRE endpoints programmatically. x402 payment is signed per request with no human in the loop.
You want full control over your funds. No custodial risk. Your wallet, your keys.
You're running a data pipeline that makes hundreds of calls per hour. Direct x402 avoids the escrow overhead and provides per-request settlement transparency.
***
## Security Tradeoffs
| Risk | Escrow | Direct x402 |
| -------------------- | --------------------------------------------- | -------------------------------- |
| Key compromise | HYRE holds encrypted keys -- trust the server | Self-custody -- you hold keys |
| Payment verification | Internal ledger (trust HYRE) | On-chain per-request (trustless) |
| Withdrawal risk | Depends on HYRE availability | N/A |
| Overspend protection | Balance cap (can't spend more than deposited) | Payment signed per request |
For maximum security and trust minimization, use **direct x402** with a self-custody wallet. The escrow mode trades some trust assumptions for convenience.
# Supported Chains
Source: https://docs.hyreagent.fun/payment/supported-chains
HYRE accepts USDC payments on Solana, Base, and SKALE.
# Supported Chains
HYRE accepts x402 payments on three chains. All chains return identical API data -- the only difference is the payment network and gas cost.
***
## Chain Comparison
| | Solana | Base | SKALE |
| ------------------- | ---------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| **Network ID** | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | `eip155:8453` | `eip155:1187947933` |
| **Gas token** | SOL | ETH | sFUEL |
| **Gas cost** | \~\$0.0005 (sponsored) | \~\$0.01 | Free |
| **USDC contract** | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | `0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20` |
| **Pay-to address** | `7G73PLhKvAPBGTzG5ESAE4coE7QrVeTTKfhTxQZbyGgC` | `0xb5998e11E666Fd1e7f3B8e8d9122A755eec1E9b7` | `0xb5998e11E666Fd1e7f3B8e8d9122A755eec1E9b7` |
| **Facilitator** | Dexter | PayAI | PayAI |
| **Facilitator URL** | `https://x402.dexter.cash` | `https://facilitator.payai.network` | `https://facilitator.payai.network` |
| **Settlement time** | \~400ms | \~2s | \~1s |
| **API prefix** | `/` (root) | `/base/` | `/skale/` |
| **Explorer** | [Solscan](https://solscan.io) | [BaseScan](https://basescan.org) | [SKALE Explorer](https://elated-tan-skat.explorer.mainnet.skalenodes.com) |
***
## Solana (Recommended)
Solana is the primary payment chain for HYRE. Gas fees are sponsored by the HYRE fee payer, so callers pay only the endpoint price in USDC.
* **Facilitator:** Dexter (`x402.dexter.cash`)
* **Payment format:** Solana transaction with USDC transfer
* **URL prefix:** Root paths (`/trenches/new-tokens`, `/defi/tvl`, etc.)
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/defi/tvl \
-H "X-PAYMENT: " \
-H "Content-Type: application/json" \
-d '{"chain": "solana"}'
```
***
## Base
Base (Coinbase L2) offers low gas fees and wide EVM wallet compatibility.
* **Facilitator:** PayAI (`facilitator.payai.network`)
* **Payment format:** EIP-3009 TransferWithAuthorization (EIP-712 signed)
* **URL prefix:** `/base/` prefix
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/base/defi/tvl \
-H "X-PAYMENT: " \
-H "Content-Type: application/json" \
-d '{"chain": "solana"}'
```
***
## SKALE
SKALE offers zero gas fees through its sFUEL mechanism. Ideal for cost-sensitive agents and high-frequency queries.
* **Facilitator:** PayAI (`facilitator.payai.network`)
* **Payment format:** EIP-3009 TransferWithAuthorization (EIP-712 signed)
* **URL prefix:** `/skale/` prefix
* **Chain name:** SKALE Europa (chain ID: 1187947933)
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/skale/defi/tvl \
-H "X-PAYMENT: " \
-H "Content-Type: application/json" \
-d '{"chain": "solana"}'
```
SKALE USDC is bridged from Ethereum mainnet via the SKALE Bridge. The USDC contract on SKALE is `0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20`.
***
## RPC Endpoints
| Chain | RPC URL |
| ------ | ----------------------------------------------------- |
| Solana | Use any Solana RPC (e.g., Helius, Alchemy, QuickNode) |
| Base | `https://mainnet.base.org` |
| SKALE | `https://mainnet.skalenodes.com/v1/elated-tan-skat` |
# x402 Protocol
Source: https://docs.hyreagent.fun/payment/x402-protocol
How HYRE uses the HTTP 402 Payment Required protocol for machine-to-machine payments.
# x402 Protocol
HYRE uses the **x402** protocol for payment -- an extension of HTTP that turns the `402 Payment Required` status code into a machine-readable payment flow. Agents pay per request with no API keys, no OAuth, and no subscriptions.
***
## How x402 Works
```bash theme={null}
curl https://mpp.hyreagent.fun/defi/tvl
```
The server returns HTTP 402 with payment requirements in the response body.
```json theme={null}
{
"x402Version": 1,
"accepts": [
{
"scheme": "exact",
"network": "solana",
"maxAmountRequired": "1000",
"resource": "https://mpp.hyreagent.fun/defi/tvl",
"payTo": "7G73PLhKvAPBGTzG5ESAE4coE7QrVeTTKfhTxQZbyGgC",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"description": "Total Value Locked across chains",
"maxTimeoutSeconds": 300
}
]
}
```
The agent constructs a payment payload, signs it with its wallet, base64-encodes it, and attaches it as the `X-PAYMENT` header.
```bash theme={null}
curl -X POST https://mpp.hyreagent.fun/defi/tvl \
-H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwi..." \
-H "Content-Type: application/json" \
-d '{"chain": "solana"}'
```
The HYRE server forwards the payment to a **facilitator** that verifies the signature and settles the USDC transfer on-chain. If valid, the server processes the request and returns data.
***
## Facilitators
HYRE uses two facilitators depending on the payment chain:
| Chain | Facilitator | URL | Gas |
| ------ | ----------- | ----------------------------------- | ---------------------- |
| Solana | Dexter | `https://x402.dexter.cash` | Sponsored by HYRE |
| Base | PayAI | `https://facilitator.payai.network` | Caller pays (\~\$0.01) |
| SKALE | PayAI | `https://facilitator.payai.network` | Free (sFUEL) |
The facilitator acts as a neutral third party:
1. **Verify** -- Checks the payment signature is valid and the amount is sufficient.
2. **Settle** -- Executes the USDC transfer on-chain after the server delivers data.
***
## Payment Header Format
The `X-PAYMENT` header contains a base64-encoded JSON object:
```json theme={null}
{
"x402Version": 1,
"scheme": "exact",
"network": "solana",
"payload": {
"signature": "",
"transaction": ""
}
}
```
For EVM chains (Base, SKALE), the payload contains an EIP-712 signed authorization instead of a Solana transaction.
***
## Discovery
Agents can discover HYRE's payment requirements programmatically:
```bash OpenAPI spec theme={null}
curl https://mpp.hyreagent.fun/openapi.json | jq '.info["x-payment-protocols"]'
```
```bash Agent card theme={null}
curl https://mpp.hyreagent.fun/.well-known/agent-card.json | jq '.capabilities.x402'
```
```bash x402 discovery theme={null}
curl https://mpp.hyreagent.fun/.well-known/x402 | jq
```
***
## Pay-To Addresses
| Chain | Address |
| ----------- | ---------------------------------------------- |
| Solana | `7G73PLhKvAPBGTzG5ESAE4coE7QrVeTTKfhTxQZbyGgC` |
| Base (EVM) | `0xb5998e11E666Fd1e7f3B8e8d9122A755eec1E9b7` |
| SKALE (EVM) | `0xb5998e11E666Fd1e7f3B8e8d9122A755eec1E9b7` |
Root paths (`/`) only accept Solana payments. Use `/base/*` for Base and `/skale/*` for SKALE. Sending an EVM payment to a root path returns a 402 redirect hint.
# Chat Agent
Source: https://docs.hyreagent.fun/playground/chat-agent
How the Gemini-powered chat agent interprets questions and selects DeFi tools.
# Chat Agent
The Playground chat agent is powered by **Gemini 2.5 Flash-Lite** -- a fast, low-latency model optimized for tool selection and conversational DeFi analysis.
***
## Agent Capabilities
The agent can:
* **Auto-detect addresses** -- Paste a Solana token mint or wallet address and the agent identifies it and selects the right tool.
* **Multi-tool orchestration** -- Complex questions may trigger multiple endpoint calls in sequence.
* **Contextual follow-ups** -- The agent remembers conversation context for follow-up questions.
* **Explain results** -- Raw data is summarized in natural language with actionable takeaways.
***
## Tool Proposal Cards
Before executing a paid endpoint, the agent displays a **tool proposal card** showing:
* The endpoint name and description
* The price that will be deducted
* The parameters that will be sent
* An "Execute" button (or auto-execute if enabled)
This gives users visibility into what the agent is doing and how much it costs before any payment occurs.
***
## Model Details
| Property | Value |
| -------------- | ------------------------------------------ |
| Model | Gemini 2.5 Flash-Lite |
| Provider | Google AI |
| Latency | \~200-500ms first token |
| Context window | 1M tokens |
| Streaming | Yes (SSE) |
| JSON mode | Supported |
| Cost | $0.10 / $0.40 per 1M tokens (input/output) |
The chat agent model (Gemini) is separate from the tiered LLM cascade used to enrich API responses (Gemini, OpenServ SERV on decision endpoints, with OpenRouter/Venice fallback). The chat agent handles conversation flow and tool selection. The cascade handles data interpretation.
***
## Example Conversations
**User:** What's the verdict on 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU?
**Agent:** I'll run a full token verdict analysis on this mint address.
*\[Calls POST /trenches/token-verdict with mint parameter]*
**Result:** This token has 847 holders with significant sniper concentration (top 5 wallets hold 34%). The bonding curve is at 72% completion. Dev wallet still holds 8%. **Signal: avoid** (confidence: 0.82).
**User:** What are the best Meteora pools for SOL-USDC right now?
**Agent:** I'll check pool recommendations for SOL-USDC.
*\[Calls POST /lp/pools-recommend with base=SOL, quote=USDC]*
**Result:** Top recommended pool is the SOL-USDC 1bp bin step pool with 127% APR and \$4.2M TVL. Suggested strategy: spot distribution, range +/-5%. **Signal: add\_liquidity** (confidence: 0.91).
**User:** Is this wallet worth following? vhu9Nc7EQi6dpvk9R6GyrDjgrgnR2oyfRAeeYVmQCAp
**Agent:** I'll pull a full wallet intelligence profile.
*\[Calls POST /traders/wallet-intel with address parameter]*
**Result:** 30-day profile shows a sniper archetype with 73% win rate on meme coins. Average hold time: 4.2 hours. Net PnL: +\$12,400. Copy-worthiness score: 7.8/10. **Signal: follow** (confidence: 0.88).
***
## Rate Limits
The chat agent has no artificial rate limits. Query frequency is bounded only by your escrow balance. The underlying Gemini model processes requests in real-time with sub-second latency.
# Escrow Wallet
Source: https://docs.hyreagent.fun/playground/escrow-wallet
Custodial wallet system for zero-friction DeFi queries in the Playground.
# Escrow Wallet
The Playground uses a custodial wallet system so users can query HYRE endpoints without manual transaction signing. Deposit USDC once, and the agent spends micro-fees automatically.
***
## How It Works
When a user signs in via Privy, the backend generates a new wallet keypair. The private key is encrypted with AES-256-GCM and stored in Cloudflare D1.
The user sends USDC to their custodial wallet address. Three chains are supported:
| Chain | Gas | USDC Contract |
| ------ | ---------------- | ---------------------------------------------- |
| Solana | SOL (\~\$0.0005) | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| Base | ETH (\~\$0.01) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| SKALE | sFUEL (free) | `0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20` |
The backend monitors incoming transfers and updates the user's balance. The current balance is visible in the Playground sidebar.
When the chat agent calls a HYRE endpoint, the backend deducts the endpoint price from the escrow balance before forwarding the request. No signing popups.
Users can withdraw their remaining USDC balance to any external wallet at any time via the Playground settings.
***
## Encryption
| Property | Value |
| -------------- | -------------------------------------- |
| Algorithm | AES-256-GCM |
| Key derivation | Per-user unique encryption key |
| Storage | Cloudflare D1 (SQLite at edge) |
| Access | Backend only (never exposed to client) |
The encryption key is derived from the user's Privy ID and a server-side secret. The private key cannot be reconstructed without both components.
***
## Balance Model
The escrow system uses an optimistic balance model:
1. **Check** -- Before calling a HYRE endpoint, verify the user has sufficient balance.
2. **Deduct** -- Subtract the endpoint price from the in-memory balance.
3. **Call** -- Forward the request to the HYRE API with an internal auth header (bypasses x402).
4. **Confirm** -- On success, persist the deduction. On failure, refund the balance.
This ensures users are never charged for failed requests.
***
## Supported Chains
* Gas token: SOL
* Gas cost: \~\$0.0005 per transaction
* USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
* Settlement: \~400ms
* Facilitator: Dexter (`x402.dexter.cash`)
* Gas token: ETH
* Gas cost: \~\$0.01 per transaction
* USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
* Settlement: \~2s
* Facilitator: PayAI (`facilitator.payai.network`)
* Gas token: sFUEL (free)
* Gas cost: Zero
* USDC: `0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20` (bridged)
* Settlement: \~1s
* Facilitator: PayAI (`facilitator.payai.network`)
* Best for: cost-sensitive agents and high-frequency queries
# Agent Playground
Source: https://docs.hyreagent.fun/playground/overview
Chat with an AI agent that calls HYRE endpoints on your behalf. No wallet setup required.
# Agent Playground
The HYRE Agent Playground at [hyreagent.fun/chat](https://hyreagent.fun/chat) is a chat interface where an AI agent interprets your DeFi questions, selects the right tools, pays the micro-fee from your custodial wallet, and returns enriched results inline.
Think of it as ChatGPT for DeFi, backed by real-time on-chain data and paid transparently per query.
***
## How It Works
Type a natural language question like *"What's the verdict on this token: 7xKX..."* or *"Show me top yielding Meteora pools"*.
The chat agent (Gemini 2.5 Flash-Lite) analyzes your question and proposes one or more HYRE tools to call. You see a tool proposal card before execution.
The backend signs an EIP-3009 `TransferWithAuthorization` from your custodial wallet. No signing popups. The fee is deducted from your escrow balance.
The AI-enriched response is displayed inline with the raw data, insight, signal, and confidence score. The agent summarizes the key takeaways.
***
## Architecture
```
User (browser)
|
v
Privy Auth (JWT)
|
v
Chat Agent (Gemini 2.5 Flash-Lite)
|
v
Tool Router --> HYRE API (x402 payment via escrow)
|
v
Response + AI Summary
```
***
## Available Tool Families
The chat agent can call any of these tool families:
| Tool Family | Endpoints | Use Case |
| ------------ | --------- | -------------------------------------------- |
| Trenches | 7 | New tokens, snipers, verdicts, graduating |
| Traders | 6 | Wallet PnL, positions, whale tracking |
| LP Analytics | 6 | Pool search, recommendations, rebalance |
| DeFi | 2 | TVL rankings, yield opportunities |
| Smart Money | 4 | Nansen flow intel, screener, wallet profiles |
| Cross-chain | 2 | Bridge quotes, yield migration |
| Ask | 1 | Natural language catch-all |
The agent auto-detects Solana token mints and wallet addresses in your messages. You can paste an address directly and the agent will figure out the right endpoint.
***
## Key Differences from Direct API
| Feature | Playground | Direct x402 |
| --------- | --------------------- | ------------------------ |
| Auth | Privy (email/social) | Wallet signature |
| Payment | Custodial escrow | On-chain per request |
| Interface | Chat UI | HTTP API |
| Signing | Automatic (no popups) | Client-side |
| Best for | Exploration, research | Automation, bots, agents |
# Privy Authentication
Source: https://docs.hyreagent.fun/playground/privy-auth
How email and social login works in the HYRE Agent Playground.
# Privy Authentication
The Agent Playground uses [Privy](https://privy.io) for authentication. Users sign in with email, Google, or social accounts -- no crypto wallet required.
***
## Auth Flow
Navigate to [hyreagent.fun/chat](https://hyreagent.fun/chat). The Privy modal appears for new users.
Privy supports email (magic link), Google, Twitter, Discord, and other OAuth providers. No seed phrases or browser extensions needed.
On successful login, Privy issues a JWT (JSON Web Token) containing the user's ID and linked wallet addresses.
Every request to `/playground/*` endpoints includes the Privy JWT in the `Authorization` header. The backend validates the signature against Privy's public keys.
If this is the user's first login, the backend provisions an AES-256-GCM encrypted custodial wallet linked to their Privy account. This wallet holds the user's escrow USDC balance.
***
## Security Model
| Layer | Implementation |
| ---------------- | ---------------------------------- |
| Auth provider | Privy (SOC 2 compliant) |
| Token format | JWT with RS256 signature |
| Validation | Server-side signature verification |
| Session lifetime | Configurable (default: 7 days) |
| Key storage | AES-256-GCM encrypted at rest |
The custodial wallet private key is encrypted and stored server-side. Users do not have direct access to the raw private key. For self-custody, use the direct x402 API instead.
***
## Why Privy?
* **Zero friction onboarding** -- Users sign in with email. No MetaMask, no seed phrases, no wallet setup.
* **Embedded wallets** -- Privy provisions wallets silently. Users interact with DeFi data without knowing they have a wallet.
* **Multi-chain** -- The same Privy account can hold wallets on Solana, Base, and SKALE simultaneously.
* **Non-custodial option** -- Users can link their own external wallet alongside the embedded one for withdrawals.
# Tool Execution
Source: https://docs.hyreagent.fun/playground/tool-execution
How the Playground agent executes paid API calls and settles payments on-chain.
# Tool Execution
When the chat agent decides to call a HYRE endpoint, it triggers a relay pattern that deducts the fee from the user's escrow balance and forwards the request to the API.
***
## Execution Flow
```
Chat Agent (Gemini)
|
| tool_call: { name: "token-verdict", params: { mint: "7xKX..." } }
|
v
/playground/call (backend)
|
|-- 1. Validate Privy JWT
|-- 2. Check escrow balance >= endpoint price
|-- 3. Deduct price from escrow
|-- 4. Forward request to HYRE API with X-Internal-Auth header
|-- 5. Return response to chat agent
|
v
Chat Agent formats + streams response to user
```
***
## Payment Signing (EVM Chains)
On Base and SKALE, the backend uses **EIP-3009 TransferWithAuthorization** to sign USDC transfers from the custodial wallet:
1. The backend decrypts the user's wallet private key.
2. It constructs a `TransferWithAuthorization` payload with:
* `from`: user's custodial wallet
* `to`: HYRE recipient address
* `value`: endpoint price in atomic USDC
* `validAfter`: current timestamp
* `validBefore`: current timestamp + 300 seconds
3. Signs the EIP-712 typed data with the decrypted key.
4. The fee payer submits the signed authorization on-chain.
5. A real transaction hash is returned and verifiable on the block explorer.
On Solana, the escrow uses an internal balance ledger with periodic on-chain settlement rather than per-query transactions. This reduces gas overhead.
***
## Internal Auth Bypass
The `/playground/call` endpoint bypasses the x402 payment middleware using a shared secret (`MPP_SECRET_KEY`):
```
X-Internal-Auth:
```
This header is only known to the Cloudflare Worker itself. External clients cannot forge it. The x402 middleware checks for this header before requiring payment, allowing the playground to pre-authorize queries via the escrow balance.
***
## Error Handling
| Scenario | Behavior |
| -------------------- | ------------------------------------------------------------------------- |
| Insufficient balance | Error returned before API call. No charge. |
| API call fails (5xx) | Balance refunded. Error shown in chat. |
| LLM cascade fails | HTTP 206 returned with raw data. User still charged (data was delivered). |
| Invalid parameters | Validation error returned. No charge. |
| Network timeout | Automatic retry once. If second attempt fails, balance refunded. |
***
## Transaction Verification
Every paid query returns metadata that can be verified:
```json theme={null}
{
"payment": {
"amount_usdc": 0.015,
"chain": "solana",
"tx_hash": "4vJ9JU1bJJE96FWSJKvHsmmFAD...",
"explorer": "https://solscan.io/tx/4vJ9JU1bJJE96FWSJKvHsmmFAD...",
"deducted_from_escrow": true
}
}
```
On SKALE, transaction hashes can be verified on the [SKALE Europa explorer](https://elated-tan-skat.explorer.mainnet.skalenodes.com).
# Pricing
Source: https://docs.hyreagent.fun/pricing
Pay-per-query pricing for all HYRE endpoints. No subscriptions. No rate limits.
# Pricing
Every HYRE endpoint charges a fixed micro-fee in USDC. Prices are denominated in **micro-USDC** (1 USDC = 1,000,000 micro-USDC) and displayed below as their USD equivalent.
No subscriptions. No monthly minimums. No rate limits. You pay only for what you use.
***
## Trenches (Meme Coin Intel)
| Endpoint | Price | Description |
| -------------------------------- | ------- | ------------------------------------- |
| `POST /trenches/new-tokens` | \$0.008 | Real-time PumpFun token launches |
| `POST /trenches/curve` | \$0.001 | Bonding curve progress for a token |
| `POST /trenches/token` | \$0.002 | Token metadata + top holders |
| `POST /trenches/token-snipers` | \$0.004 | Sniper detection (early buyers) |
| `POST /trenches/graduating` | \$0.003 | Tokens near graduation (>85%) |
| `POST /trenches/bags/new-tokens` | \$0.008 | New tokens from Bags.fm (Meteora DBC) |
| `POST /trenches/token-verdict` | \$0.015 | Full AI verdict on a token |
## Traders (Copy Trading + Whales)
| Endpoint | Price | Description |
| -------------------------------- | ------- | ---------------------------------- |
| `POST /traders/wallet-pnl` | \$0.005 | Wallet PnL (realized + unrealized) |
| `POST /traders/wallet-positions` | \$0.003 | Current token holdings with prices |
| `POST /traders/top-wallets` | \$0.008 | Top performing wallets leaderboard |
| `POST /traders/token-whales` | \$0.003 | Whale activity for a token |
| `POST /traders/token-ohlcv` | \$0.002 | Price and volume data |
| `POST /traders/wallet-intel` | \$0.012 | Full 30-day wallet intelligence |
## LP Analytics (Meteora DLMM)
| Endpoint | Price | Description |
| ----------------------------- | ------- | --------------------------------------- |
| `POST /lp/pools` | \$0.001 | All Meteora DLMM pools with analytics |
| `POST /lp/pools-recommend` | \$0.008 | AI pool recommendation for a token pair |
| `POST /lp/pool-detail` | \$0.003 | Deep analytics for a specific pool |
| `POST /lp/wallet-positions` | \$0.004 | LP positions for a wallet |
| `POST /lp/position-rebalance` | \$0.010 | Rebalance signal for a position |
| `POST /lp/pools-strategy` | \$0.020 | Full LP strategy brief |
## DeFi (Macro)
| Endpoint | Price | Description |
| ------------------- | ------- | -------------------------------- |
| `POST /defi/tvl` | \$0.001 | Total Value Locked across chains |
| `POST /defi/yields` | \$0.002 | Top yield pools multi-chain |
## Cross-Chain (deBridge)
| Endpoint | Price | Description |
| ------------------------------ | ------- | -------------------------------------- |
| `POST /debridge/quote` | \$0.002 | Cross-chain swap quote with AI verdict |
| `POST /debridge/yield-migrate` | \$0.005 | Yield migration advisor |
## Smart Money (Nansen)
| Endpoint | Price | Description |
| ------------------------------ | ------- | --------------------------------------- |
| `POST /nansen/token-screener` | \$0.025 | Find tokens smart money is accumulating |
| `POST /nansen/flow-intel` | \$0.020 | Smart trader/whale/KOL net-flow |
| `POST /nansen/pnl-leaderboard` | \$0.030 | Top PnL traders for a token |
| `POST /nansen/wallet-intel` | \$0.050 | Deep wallet profile + smart trades |
## Meta
| Endpoint | Price | Description |
| ----------- | ------- | --------------------------- |
| `POST /ask` | \$0.025 | Natural language DeFi query |
***
## Payment Split
Every payment is split automatically:
| Recipient | Share |
| ----------- | ----- |
| HYRE Wallet | 90% |
| Treasury | 10% |
Gas fees on Solana are sponsored by HYRE. On SKALE, gas is natively free (sFUEL). On Base, the caller pays standard L2 gas (\~\$0.01).
***
## Free Endpoints
These endpoints require no payment:
| Endpoint | Description |
| ---------------------------------- | ------------------------------ |
| `GET /` | Health check + service info |
| `GET /openapi.json` | OpenAPI 3.1 specification |
| `GET /.well-known/agent-card.json` | A2A + ERC-8004 agent discovery |
| `GET /.well-known/x402` | x402 resource discovery |
# Quickstart
Source: https://docs.hyreagent.fun/quickstart
Make your first paid API call in under 2 minutes.
# Quickstart
HYRE has two access paths: **direct x402 payment** for agents and scripts, or the **Agent Playground** for interactive chat.
***
## Option A: Direct x402 (for agents)
HYRE accepts USDC on three chains:
| Chain | Gas Token | Gas Cost | USDC Contract |
| ---------- | --------- | ---------- | ---------------------------------------------- |
| **Solana** | SOL | \~\$0.0005 | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| **Base** | ETH | \~\$0.01 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| **SKALE** | sFUEL | Free | `0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20` |
For zero gas fees, use SKALE. For the fastest settlement, use Solana.
Call any endpoint without a payment header. The server returns HTTP 402 with payment requirements.
```bash theme={null}
curl -s https://mpp.hyreagent.fun/defi/tvl | jq
```
```json theme={null}
{
"x402Version": 1,
"accepts": [
{
"scheme": "exact",
"network": "solana",
"maxAmountRequired": "1000",
"resource": "https://mpp.hyreagent.fun/defi/tvl",
"payTo": "7G73PLhKvAPBGTzG5ESAE4coE7QrVeTTKfhTxQZbyGgC",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
]
}
```
Use your x402-compatible client to sign the payment and attach the `X-PAYMENT` header.
```bash curl (with pre-signed header) theme={null}
curl -X POST https://mpp.hyreagent.fun/defi/tvl \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"chain": "solana", "limit": 10}'
```
```typescript x402 SDK (Solana) theme={null}
import { createX402Client } from "x402-client";
const client = createX402Client({
network: "solana",
wallet: yourSolanaWallet,
facilitator: "https://x402.dexter.cash",
});
const response = await client.fetch(
"https://mpp.hyreagent.fun/defi/tvl",
{ method: "POST", body: JSON.stringify({ chain: "solana" }) }
);
```
```python AgentCash (Python) theme={null}
# AgentCash handles x402 payment automatically
import requests
response = requests.post(
"https://mpp.hyreagent.fun/defi/tvl",
json={"chain": "solana", "limit": 10},
headers={"X-PAYMENT": agentcash.sign_payment()}
)
```
The response includes raw data, an AI insight, a signal, and a confidence score.
```json theme={null}
{
"data": {
"chains": [
{ "name": "Ethereum", "tvl_usd": 62800000000 },
{ "name": "Solana", "tvl_usd": 12400000000 }
],
"total_tvl_usd": 182400000000
},
"insight": "Solana TVL surged 12% week-over-week, driven by memecoin speculation and Meteora LP inflows. Ethereum dominance declined to 34%.",
"signal": "high_yield",
"confidence": 0.87,
"sources": ["defillama"],
"model_used": "gemini-2.5-flash-lite",
"latency_ms": 342,
"timestamp": "2026-04-17T10:30:00.000Z"
}
```
***
## Option B: Agent Playground (for humans)
The Playground at [hyreagent.fun/chat](https://hyreagent.fun/chat) provides a chat interface where an AI agent calls HYRE endpoints on your behalf.
Email, Google, or social login. No wallet needed -- Privy provisions a custodial wallet automatically.
Send USDC to your custodial wallet address (Solana, Base, or SKALE). The balance appears in real-time.
Ask questions in plain English:
* *"What are the top yielding Meteora pools right now?"*
* *"Give me a full verdict on token So11111..."*
* *"Which wallets are accumulating this token?"*
The agent picks the right tool, pays the micro-fee from your escrow balance, and returns the result inline.
***
## Chain Routing
Each chain has its own URL prefix:
| Chain | Prefix | Example |
| ------ | ---------- | ------------------------------------------ |
| Solana | `/` (root) | `https://mpp.hyreagent.fun/defi/tvl` |
| Base | `/base/` | `https://mpp.hyreagent.fun/base/defi/tvl` |
| SKALE | `/skale/` | `https://mpp.hyreagent.fun/skale/defi/tvl` |
All chains return identical data. The only difference is which payment network settles the transaction.
Root paths (`/`) accept **Solana payments only**. For Base or SKALE, you must use the chain-prefixed paths (`/base/*` or `/skale/*`).