Skip to content

api-reference-x402.md

Latest commit

 

History

History
582 lines (409 loc) · 20.2 KB

api-reference-x402.md

File metadata and controls

582 lines (409 loc) · 20.2 KB

API Reference (x402)

Developer x402 API

Technical specifications for Minara's x402 endpoints using the Pay-As-You-Go model.

Base URL: https://x402.minara.ai

{% openapi-operation spec="minara-api-x402-v2" path="/x402/chat" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/chat/expert" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/polygon/chat" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/polygon/chat/expert" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/solana/chat" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/solana/chat/expert" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/perp-trading-suggestion" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/intent-to-swap-tx" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

{% openapi-operation spec="minara-api-x402-v2" path="/x402/prediction-market-ask" method="post" %} OpenAPI minara-api-x402-v2 {% endopenapi-operation %}

Endpoints

Chat (Base Chain)

Endpoint: POST /x402/chat

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
userQuery string Yes User query content

Example Request

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "What is the current price of BTC and what are the key support levels?"
  }'

Response

Status: 201 Created

{
  "content": "BTC is currently trading at $98,450. Key support levels are at $96,500 and $94,200. The recent breakout above $97,000 with strong volume suggests bullish continuation..."
}

Chat Expert (Base Chain)

Endpoint: POST /x402/chat/expert

Ask Minara AI - Intelligent crypto assistant on Base chain with expert mode

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
userQuery string Yes User query content

Example Request

curl -X POST https://x402.minara.ai/x402/chat/expert \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Provide a comprehensive analysis of ETH including on-chain metrics and trading strategy"
  }'

Response

Status: 201 Created

{
  "content": "Comprehensive ETH Analysis:\n\n**Price Action**: ETH is trading at $3,420, consolidating near the $3,400-$3,500 range...\n\n**On-Chain Metrics**: Active addresses increased 12% week-over-week, indicating growing network activity...\n\n**Trading Strategy**: Consider accumulating on dips to $3,300 support with targets at $3,600 and $3,850..."
}

Chat (Solana Chain)

Endpoint: POST /x402/solana/chat

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
userQuery string Yes User query content

Example Request

curl -X POST https://x402.minara.ai/x402/solana/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Show me the top trending tokens on Solana right now"
  }'

Response

Status: 201 Created

{
  "content": "Top trending Solana tokens:\n1. WIF - up 24% with $45M 24h volume\n2. BONK - up 18% with strong community activity\n3. JUP - consolidating after recent pump, volume at $38M..."
}

Chat Expert (Solana Chain)

Endpoint: POST /x402/solana/chat/expert

Ask Minara AI - Intelligent crypto assistant on Solana chain with expert mode

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
userQuery string Yes User query content

Example Request

curl -X POST https://x402.minara.ai/x402/solana/chat/expert \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Analyze the liquidity distribution and whale movements for JUP token"
  }'

Response

Status: 201 Created

{
  "content": "**JUP Token Deep Analysis**\n\n**Liquidity Distribution**: Total liquidity across major DEXs is $125M, with 65% concentrated in the $0.85-$0.92 range...\n\n**Whale Activity**: Top 10 holders control 34% of supply. Detected 3 significant whale transactions in the last 24h totaling $4.2M in buys...\n\n**Risk Assessment**: Moderate liquidity risk above $1.00 mark. Consider this in position sizing..."
}

Chat (Polygon Chain)

Endpoint: POST /x402/polygon/chat

Ask Minara AI - Intelligent crypto assistant on Polygon chain

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
userQuery string Yes User query content

Example Request

curl -X POST https://x402.minara.ai/x402/polygon/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "What is the current price of BTC and what are the key support levels?"
  }'

Response

Status: 201 Created

{
  "content": "BTC is currently trading at $98,450. Key support levels are at $96,500 and $94,200. The recent breakout above $97,000 with strong volume suggests bullish continuation..."
}

Chat Expert (Polygon Chain)

Endpoint: POST /x402/polygon/chat/expert

Ask Minara AI - Intelligent crypto assistant on Polygon chain with expert mode

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
userQuery string Yes User query content

Example Request

curl -X POST https://x402.minara.ai/x402/polygon/chat/expert \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Provide a comprehensive analysis of ETH including on-chain metrics and trading strategy"
  }'

Response

Status: 201 Created

{
  "content": "**Comprehensive ETH Analysis**\n\n**Price Action**: ETH is trading at $3,420, consolidating near the $3,400-$3,500 range...\n\n**On-Chain Metrics**: Active addresses increased 12% week-over-week, indicating growing network activity...\n\n**Trading Strategy**: Consider accumulating on dips to $3,300 support with targets at $3,600 and $3,850..."
}

Trading Endpoints

Intent to Swap Transaction

Endpoint: POST /x402/intent-to-swap-tx

Convert natural language trading intent into an executable swap transaction payload. Compatible with OKX DEX by default.

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Description
intent string Yes Natural language swap intent (e.g., "swap 0.1 ETH to USDC")
walletAddress string Yes User wallet address (0x...)
chain string No Chain name (e.g., "base", "ethereum", "bsc", "arbitrum", "optimism")

Example Request

curl -X POST https://x402.minara.ai/x402/intent-to-swap-tx \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "swap 0.1 ETH to USDC",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "chain": "base"
  }'

Response

Status: 201 Created

{
  "transaction": {
    "chain": "base",
    "inputTokenAddress": "0x4200000000000000000000000000000000000006",
    "inputTokenSymbol": "ETH",
    "outputTokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "outputTokenSymbol": "USDC",
    "amount": "0.1",
    "amountPercentage": 100,
    "slippagePercent": "0.5"
  }
}

Perpetual Trading Suggestion

Endpoint: POST /x402/perp-trading-suggestion

Get AI-powered perpetual trading suggestions with long/short recommendations, entry price, stop loss, take profit levels, and confidence score based on comprehensive market analysis.

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Default Description
symbol string Yes - Trading symbol (e.g., "BTC", "ETH", "SOL")
style string No "scalping" Trading style: "scalping", "day-trading", or "swing-trading"
marginUSD number No 1000 Margin in USD
leverage number No 10 Leverage multiplier (max: 40)
strategy string No "max-profit" Strategy type (more strategies coming soon)

Example Request

curl -X POST https://x402.minara.ai/x402/perp-trading-suggestion \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC",
    "style": "day-trading",
    "marginUSD": 1000,
    "leverage": 10,
    "strategy": "max-profit"
  }'

Response

Status: 201 Created

{
  "entryPrice": 98450,
  "side": "long",
  "stopLossPrice": 96200,
  "takeProfitPrice": 102800,
  "confidence": 78,
  "reasons": [
    "BTC broke above key resistance at $97,500 with strong volume",
    "RSI at 62 indicates bullish momentum without being overbought",
    "MACD showing bullish crossover on 4H timeframe",
    "Volume profile shows accumulation at current levels"
  ],
  "risks": [
    "Potential pullback at $100,000 psychological resistance",
    "High volatility expected around upcoming Fed meeting",
    "Funding rates on major exchanges trending higher"
  ]
}

Prediction Market Analysis (Base Chain)

Endpoint: POST /x402/prediction-market-ask

AI-powered prediction market analysis. Analyze prediction market events and get probability estimates for each outcome with detailed reasoning.

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Parameter Type Required Default Description
link string Yes - Prediction market page link (e.g., Polymarket event URL)
mode string Yes - Chat mode: "fast" or "expert"
only_result boolean No false Only return prediction probabilities without reasoning
customPrompt string No - Custom instructions to guide the analysis

Example Request

curl -X POST https://x402.minara.ai/x402/prediction-market-ask \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://polymarket.com/event/will-there-be-another-us-government-shutdown-by-january-31",
    "mode": "fast",
    "only_result": false,
    "customPrompt": "Focus on recent news and sentiment analysis. Be more conservative in probability estimates."
  }'

Response

Status: 201 Created

{
  "predictions": [
    {
      "outcome": "Donald Trump",
      "yesProb": 0.65,
      "noProb": 0.35
    },
    {
      "outcome": "Kamala Harris",
      "yesProb": 0.3,
      "noProb": 0.7
    }
  ],
  "reasoning": "Based on recent polling data and historical trends, Trump maintains a slight lead in key swing states. However, the race remains highly competitive with significant uncertainty..."
}

Prediction Market Analysis (Polygon Chain)

Endpoint: POST /x402/polygon/prediction-market-ask

AI-powered prediction market analysis on Polygon chain. Same functionality as Base chain endpoint.

Request

Headers:

  • x-payment-response (required) - Payment proof token from x402 protocol
  • Content-Type: application/json

Body Parameters:

Same as Base chain endpoint above.

Example Request

curl -X POST https://x402.minara.ai/x402/polygon/prediction-market-ask \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://polymarket.com/event/will-there-be-another-us-government-shutdown-by-january-31",
    "mode": "fast",
    "only_result": false
  }'

Response

Status: 201 Created

Same response format as Base chain endpoint.

Error Responses

402 Payment Required

Initial request without payment credentials will return:

{
  "error": "payment_required",
  "message": "Payment required to access this resource",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0x...",
    "chain": "base"
  }
}

401 Unauthorized

Invalid or expired payment proof:

{
  "error": "unauthorized",
  "message": "Invalid payment response token"
}

400 Bad Request

Invalid request parameters:

{
  "error": "bad_request",
  "message": "Missing required parameter: userQuery"
}

Rate Limits

x402 endpoints are rate-limited per wallet address:

  • AI Endpoints: 60 requests per minute
  • Trading Endpoints: 30 requests per minute

Exceeding rate limits will return:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again in 30 seconds.",
  "retryAfter": 30
}

Notes

  • All x402 endpoints require the x-payment-response header after completing the payment challenge
  • Prices are subject to change based on network conditions
  • For more information on x402 protocol, see x402 Documentation