SparkHood API Integration Guide

SparkHood API exposes standardized blockchain intelligence for wallets, tokens, markets, contracts, and swap planning. It also provides skill discovery, service health, and administrative API-key management.

Protected intelligence endpoints use a user API key in the X-API-Key header. Responses are JSON, include a request identifier where applicable, and use consistent metadata for cache state, warnings, and execution timing.

Quick Start

Complete these steps to make your first authenticated request in under one minute.

Step 1: Obtain an API key

Ask an authorized account administrator to create a user API key for your application. The key is displayed only once when it is created and normally begins with rh_live_.

Warning: Never place an API key in source control, browser code, screenshots, or support messages. Store it in a secret manager or protected environment variable.

Step 2: Make your first request

Replace the example address and key, then request a Robinhood Chain wallet profile:

curl "https://api.sparkhood.net/api/v1/wallet/0x1111111111111111111111111111111111111111?chain=robinhood" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

Step 3: Read the response

A successful request returns intelligence data and a correlation ID. The exact registered capability results may vary, but the envelope remains stable:

{
  "success": true,
  "data": {
    "get_wallet": {
      "success": true,
      "data": {
        "address": "0x1111111111111111111111111111111111111111",
        "chain": "robinhood",
        "score": 78,
        "portfolio_value_usd": 12543.82
      },
      "execution_time_ms": 74.6,
      "cached": false,
      "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833"
    }
  },
  "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833"
}

The X-Request-ID response header contains the same correlation identifier. Keep it when diagnosing a failed request.

Step 4: Explore Intelligence endpoints

Start with the canonical analysis endpoints for agent-ready data:

• Wallet: /api/v1/wallet/{address}/analysis
• Token: /api/v1/token/{address}/analysis
• Market: /api/v1/market/trending
• Contract: /api/v1/contract/{address}/analysis
• Swap planning: /api/v1/swap/quote

Table of Contents

• Quick Start
• Base URL
• API Versioning
• Authentication
• Authentication Flow
• Response Conventions
• Error Responses
• AI Chat Orchestrator
• Wallet Intelligence
• Token Intelligence
• Market Intelligence
• Contract Intelligence
• Swap Intelligence
• User API Keys
• User Activity and Analysis History
• Skill Discovery
• Health Monitoring
• Common Examples
• SDK Examples
• Supported Chains
• Pagination
• Rate Limits
• Caching
• Retries and Timeouts
• API-key Security Best Practices
• FAQ
• Changelog

Base URL

Local development:

https://api.sparkhood.net

Production placeholder:

https://api.sparkhood.net

All versioned endpoints in this guide use /api/v1. Replace the placeholder host with the URL supplied for your deployment.

API Versioning

The current public API version is v1, represented by the /api/v1 URL prefix.

Clients should ignore unknown response fields so compatible additions do not require immediate client releases. Validate the fields your application uses rather than rejecting an entire response because a new optional field appears.

Note: The application release number and the public API version are related but independent. A backend release can improve v1 without introducing a new public API version.

Authentication

User API key

Wallet, token, market, contract, and swap requests require:

X-API-Key: rh_live_xxxxxxxxx

curl "https://api.sparkhood.net/api/v1/wallet/0x1111111111111111111111111111111111111111" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Store user keys as secrets. A newly created key is returned only once; later list operations return its prefix rather than the plaintext credential.

Administrative master key

MASTER_API_KEY is reserved for API-key administration. Send it only to the administrative endpoints:

X-Master-Key: your-administrative-secret

Do not use or distribute the master key as an application user credential.

Public endpoints

Health monitoring and skill discovery do not require X-API-Key. Diagnostic endpoint availability is deployment-dependent and should be disabled in production.

Authentication Flow

Dashboard or administrative system
               ↓
       Generate a user API key
               ↓
   Store the key in a secret manager
               ↓
       Call an Intelligence API

The two credential types have distinct responsibilities:

1. A trusted administrator authenticates with the master key and creates a named user key for a wallet address.
2. The plaintext user key is returned once and transferred to the application through a secure channel.
3. The application stores the key as a secret and sends it in X-API-Key.
4. The API validates that the key exists and is active before running protected intelligence operations.
5. An administrator can deactivate or revoke the key without changing other application credentials.

Warning: The master key has administrative authority. Never ship it with an agent, mobile application, web frontend, or customer integration.

Response conventions

Intelligence endpoints return either a standard envelope or a skill-specific canonical response.

Example standard response:

{
  "success": true,
  "data": {
    "result": "available"
  },
  "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833"
}

Example canonical analysis response:

{
  "analysis": {
    "wallet": {
      "address": "0x1111111111111111111111111111111111111111",
      "chain": "robinhood",
      "score": 78,
      "dna": {
        "trading_style": "active",
        "risk_profile": "balanced"
      },
      "risk_flags": ["high_position_concentration"]
    },
    "portfolio": {
      "total_value_usd": 12543.82,
      "total_profit_usd": 2184.35,
      "position_count": 8,
      "performance": { "winrate": 0.68, "buy_count": 46, "sell_count": 31 }
    },
    "holdings": [
      {
        "token": { "symbol": "RHO", "name": "Robinhood Token" },
        "balance": 18420.5,
        "usd_value": 7644.51,
        "unrealized_profit": 932.18
      }
    ],
    "activity": {
      "total": 42,
      "buys": 24,
      "sells": 18,
      "volume_usd": 48219.7,
      "items": [
        { "type": "buy", "token_amount": 1250.0, "cost_usd": 518.75, "timestamp": 1785897000 }
      ]
    },
    "created_tokens": {
      "total_created": 1,
      "open_count": 1,
      "tokens": [
        { "symbol": "ALPHA", "market_cap": 420000.0, "holders": 1830, "is_open": true }
      ]
    },
    "ai": {
      "summary": "Active wallet with positive realized performance and moderate concentration risk.",
      "risk_level": "medium",
      "confidence": 0.86
    },
    "metadata": {
      "success": true,
      "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833",
      "execution_time_ms": 81.4,
      "cached": false,
      "warnings": ["Activity coverage is limited to the requested lookback window."]
    }
  }
}

Clients may supply X-Request-ID; otherwise, the server creates one. Always log this value when reporting an integration issue.

Error responses

Errors use the following shape:

{
  "success": false,
  "error": {
    "code": "authentication_error",
    "message": "Invalid API key.",
    "details": null
  },
  "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833"
}

Example validation error:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "loc": ["query", "limit"],
        "msg": "Input should be less than or equal to 100",
        "type": "less_than_equal"
      }
    ]
  },
  "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833"
}

AI Chat Orchestrator

The Chat Orchestrator converts a natural-language request into one or more calls to existing Intelligence capabilities, then returns a structured conversational summary. It is an orchestration API—not a general-purpose chatbot—and it does not accept follow-up conversation state.

Orchestrate an Intelligence request

• Method: POST
• URL: /api/v1/chat
• Headers: X-API-Key, Content-Type: application/json

curl -X POST "https://api.sparkhood.net/api/v1/chat" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"conversation_id":null,"message":"Analyze wallet 0x1111111111111111111111111111111111111111 and summarize its recent on-chain behavior."}'

{
  "conversation_id": "7bf95f6a-2574-47d5-b03b-7c23e52baeb2",
  "message_id": "608045ed-8824-412d-806f-cdd77f23f584",
  "intent": "wallet",
  "tool": "wallet",
  "ai": {
    "opening": "I analyzed the requested wallet using Wallet Intelligence.",
    "analysis": "The supplied data reports a wallet score of 78, eight positions, and 42 recent activities. Total portfolio value is $12,543.82 with $2,345.71 in total profit.",
    "conclusion": "The wallet shows active and profitable behavior, with position concentration identified as the principal available risk signal."
  },
  "data": {
    "analysis": {
      "wallet": {
        "address": "0x1111111111111111111111111111111111111111",
        "chain": "robinhood",
        "score": 78,
        "risk_flags": ["high_position_concentration"]
      },
      "portfolio": {
        "total_value_usd": 12543.82,
        "total_profit_usd": 2345.71,
        "position_count": 8
      },
      "holdings": [
        {
          "token": {"symbol": "RHO", "price": 0.415},
          "balance": 18420.5,
          "usd_value": 7644.51
        }
      ],
      "activity": {
        "total": 42,
        "buys": 24,
        "sells": 18,
        "volume_usd": 48219.7,
        "items": [
          {"type": "buy", "token_amount": 1250.0, "cost_usd": 518.75}
        ]
      },
      "created_tokens": {
        "total_created": 1,
        "tokens": [{"symbol": "ALPHA", "market_cap": 420000.0}]
      },
      "ai": null,
      "metadata": {
        "success": true,
        "request_id": "8d46d51c-864e-4c8d-8971-ad3badfc45c0",
        "execution_time_ms": 181.2,
        "cached": false,
        "warnings": ["Activity coverage is limited to the available window."]
      }
    }
  },
  "metadata": {
    "request_id": "8d46d51c-864e-4c8d-8971-ad3badfc45c0",
    "chain": "robinhood",
    "addresses": ["0x1111111111111111111111111111111111111111"],
    "skills": ["wallet_analysis"],
    "execution_time_ms": 284.7,
    "ai_generated": true,
    "warnings": ["Activity coverage is limited to available normalized data."]
  }
}

The data object is the complete endpoint-equivalent canonical response. For example, wallet chat data has the same shape and values as GET /api/v1/wallet/{address}/analysis; Chat does not flatten, select, or rename any Intelligence fields.

The top-level tool identifies a single Intelligence capability. Future requests using multiple capabilities use tools and group complete responses under their tool names:

{
  "intent": "multi",
  "tools": ["wallet", "market", "contract"],
  "ai": {
    "opening": "I analyzed the requested wallet, market, and contract intelligence.",
    "analysis": "The summary is based on every populated field in the three canonical responses.",
    "conclusion": "Review each complete tool response for the underlying facts and limitations."
  },
  "data": {
    "wallet": {"analysis": {"wallet": {"score": 78}}},
    "market": {"tokens": [{"token": {"symbol": "RHO"}}]},
    "contract": {"analysis": {"verification": {"verified": true}}}
  },
  "metadata": {
    "request_id": "cb687975-217f-4f6b-b061-841240f1523f",
    "chain": "robinhood",
    "addresses": ["0x1111111111111111111111111111111111111111"],
    "skills": ["wallet_analysis", "market_trending_tokens", "contract_analysis"],
    "execution_time_ms": 492.4,
    "ai_generated": true,
    "warnings": ["Multi-tool orchestration is reserved for a future release."]
  }
}

Supported intents

Intent selection is deterministic. Version 1 does not use AI to select a capability.

The parser recognizes Robinhood, Ethereum, BNB Chain, Base, and Solana terminology. For address-based analysis, at least one valid address is required. Swap quotes require two token addresses and an amount.

When the intent is unknown or required parameters are missing, the API returns a deterministic explanatory response and does not invoke AI generation. For successful requests, the AI reads the full canonical data response, ignores null values, and must not fabricate missing values or statistics.

Conversation persistence

Every Chat request stores a user message and an assistant message. Conversations belong to the wallet associated with X-API-Key; another owner receives 404 Not Found rather than information about the conversation.

New assistant messages store the complete response returned by POST /api/v1/chat, including conversation and message identifiers, intent, tool selection, AI presentation, canonical Intelligence data, message, and metadata. The stored object is returned unchanged by Chat History and conversation detail endpoints. Existing messages that contain the older AI-only response shape remain readable for backward compatibility. Deleting a conversation deletes its messages but preserves Analysis History.

Get complete chat history

GET /api/v1/chat/history returns the authenticated user's complete, paginated chat history without requiring a conversation ID.

Authentication

• Requires a valid User API Key in the X-API-Key header.
• Master API Keys are not allowed.
• Invalid API keys return 401 Unauthorized.

Query parameters

Behavior

• Returns only conversations owned by the authenticated user.
• Does not require conversation_id.
• Conversations are sorted by updated_at descending.
• Messages are sorted by created_at ascending.
• Includes both user and assistant messages.
• Assistant messages include the original stored response_json as response without modification.
• Supports pagination using limit and offset.

Example request

curl "https://api.sparkhood.net/api/v1/chat/history?limit=20&offset=0" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "total": 2,
  "items": [
    {
      "id": "chat_01",
      "title": "Deploy ERC20",
      "created_at": "2026-08-05T10:00:00Z",
      "updated_at": "2026-08-05T10:05:00Z",
      "last_message_at": "2026-08-05T10:05:00Z",
      "message_count": 4,
      "messages": [
        {
          "id": "msg_1",
          "role": "user",
          "content": "How do I deploy ERC20?",
          "created_at": "2026-08-05T10:00:00Z"
        },
        {
          "id": "msg_2",
          "role": "assistant",
          "content": "To deploy an ERC20...",
          "response": {
            "conversation_id": "chat_01",
            "message_id": "msg_2",
            "intent": "contract",
            "tool": "contract",
            "ai": {
              "opening": "I can help explain the deployment flow.",
              "analysis": "The response is based on the complete available Intelligence data.",
              "conclusion": "Review the deployment and verification requirements before proceeding."
            },
            "data": {
              "analysis": {
                "contract": {
                  "address": "0x3333333333333333333333333333333333333333",
                  "verified": true
                }
              }
            },
            "metadata": {
              "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833",
              "chain": "robinhood",
              "addresses": ["0x3333333333333333333333333333333333333333"],
              "skills": ["contract_analysis"],
              "execution_time_ms": 284.7,
              "ai_generated": true,
              "warnings": []
            }
          },
          "created_at": "2026-08-05T10:00:02Z"
        }
      ]
    }
  ]
}

Notes

• response is the complete POST /api/v1/chat response and is returned exactly as stored in the database.
• data retains the complete canonical Intelligence response.
• ai, intent, tool or tools, message, and metadata retain their original values when present.
• The endpoint never rebuilds or transforms the assistant response.
• Older records containing only the AI fields are returned in their original legacy shape.
• Messages are returned in chronological order.
• Conversation IDs are not required by the client.
• This endpoint is intended for rendering the complete chat history UI.

Performance notes

• Conversations are paginated.
• Messages are loaded using a single bulk query.
• N+1 queries are avoided.
• The total conversation count is returned with the response.

Possible responses

Validation guarantees

• Empty history returns success with total = 0 and items = [].
• Pagination supports limit and offset.
• Only the authenticated user's conversations are returned.
• Assistant response payloads are preserved exactly as stored.

List conversations

• Method: GET
• URL: /api/v1/chat/conversations
• Header: X-API-Key

curl "https://api.sparkhood.net/api/v1/chat/conversations" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

[
  {
    "id": "7bf95f6a-2574-47d5-b03b-7c23e52baeb2",
    "title": "Analyze Wallet",
    "last_message": "I analyzed the requested wallet. The available data reports active behavior.",
    "updated_at": "2026-08-05T15:10:00Z",
    "message_count": 4
  }
]

Get a conversation

• Method: GET
• URL: /api/v1/chat/conversations/{id}
• Header: X-API-Key

Returns conversation metadata and all messages ordered by creation time. Assistant messages expose the stored complete Chat API response as response; the value is not reconstructed or transformed. Older AI-only stored responses are returned unchanged for backward compatibility. Messages also include their intent, tools, and analysis_history_ids references.

curl "https://api.sparkhood.net/api/v1/chat/conversations/7bf95f6a-2574-47d5-b03b-7c23e52baeb2" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Rename a conversation

• Method: PATCH
• URL: /api/v1/chat/conversations/{id}
• Headers: X-API-Key, Content-Type: application/json
• Body: title, from 1 to 60 characters.

curl -X PATCH "https://api.sparkhood.net/api/v1/chat/conversations/7bf95f6a-2574-47d5-b03b-7c23e52baeb2" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Wallet Research"}'

Delete a conversation

• Method: DELETE
• URL: /api/v1/chat/conversations/{id}
• Header: X-API-Key
• Success: 204 No Content

curl -X DELETE "https://api.sparkhood.net/api/v1/chat/conversations/7bf95f6a-2574-47d5-b03b-7c23e52baeb2" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Only the conversation and its messages are deleted. Referenced Analysis History remains available.

Wallet Intelligence

Wallet Intelligence includes portfolio information; there is no standalone Portfolio API.

Get wallet intelligence

Returns a complete wallet profile assembled from registered wallet capabilities.

• Method: GET
• URL: /api/v1/wallet/{address}
• Header: X-API-Key

curl "https://api.sparkhood.net/api/v1/wallet/0x1111111111111111111111111111111111111111?chain=robinhood" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

The response uses the standard success, data, and request_id envelope. data contains the results of the available wallet intelligence capabilities.

Analyze a wallet

Returns one canonical analysis containing wallet identity, integrated portfolio, holdings, activity, created tokens, optional AI analysis, and metadata.

• Method: GET
• URL: /api/v1/wallet/{address}/analysis
• Header: X-API-Key

curl "https://api.sparkhood.net/api/v1/wallet/0x1111111111111111111111111111111111111111/analysis?chain=robinhood&include_ai=true&include_activity=true&include_created_tokens=true" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

{
  "analysis": {
    "wallet": {
      "address": "0x1111111111111111111111111111111111111111",
      "chain": "robinhood",
      "score": 78,
      "dna": { "trading_style": "active", "holding_pattern": "swing" },
      "risk_flags": ["high_position_concentration"]
    },
    "portfolio": {
      "total_value_usd": 12543.82,
      "realized_profit_usd": 1460.22,
      "unrealized_profit_usd": 724.13,
      "total_profit_usd": 2184.35,
      "position_count": 8,
      "performance": { "period": "30d", "winrate": 0.68, "pnl": 0.174 }
    },
    "holdings": [
      {
        "token": { "symbol": "RHO", "name": "Robinhood Token", "price": 0.415 },
        "balance": 18420.5,
        "usd_value": 7644.51,
        "total_profit": 932.18
      }
    ],
    "activity": {
      "total": 42,
      "buys": 24,
      "sells": 18,
      "volume_usd": 48219.7,
      "items": [
        { "type": "buy", "token_amount": 1250.0, "cost_usd": 518.75, "timestamp": 1785897000 }
      ]
    },
    "created_tokens": {
      "total_created": 1,
      "open_count": 1,
      "tokens": [
        { "symbol": "ALPHA", "market_cap": 420000.0, "holders": 1830, "is_open": true }
      ]
    },
    "ai": {
      "summary": "Profitable active wallet with consistent execution.",
      "wallet_type": "active_trader",
      "trading_style": "swing",
      "risk_level": "medium",
      "confidence": 0.86,
      "copy_trade_score": 74,
      "strengths": ["Positive 30-day PnL", "Above-average win rate"],
      "weaknesses": ["Concentrated largest position"],
      "recommendations": ["Monitor position concentration before mirroring trades"],
      "red_flags": ["high_position_concentration"],
      "wallet_personality": "disciplined momentum trader"
    },
    "metadata": {
      "success": true,
      "request_id": "7d9f0ca8-2a18-4ff4-9a1d-44a247203833",
      "execution_time_ms": 183.7,
      "cached": false,
      "warnings": ["Activity coverage is limited to the requested lookback window."]
    }
  }
}

When optional data is unavailable, the endpoint remains usable and reports non-fatal limitations in analysis.metadata.warnings.

Wallet detail endpoints

These endpoints use GET, require X-API-Key, accept an address path parameter and optional chain query parameter (default robinhood), and return the standard envelope.

curl "https://api.sparkhood.net/api/v1/wallet/0x1111111111111111111111111111111111111111/score?chain=robinhood" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Representative detail results:

{
  "score": {
    "subject": "0x1111111111111111111111111111111111111111",
    "status": "available",
    "score": 62.5,
    "metrics": { "tx_count": 1842, "sample_transaction_count": 50, "successful_transactions": 49 },
    "source": "live_clients"
  },
  "dna": {
    "subject": "0x1111111111111111111111111111111111111111",
    "status": "available",
    "metrics": { "tx_count": 1842, "sample_transaction_count": 50, "successful_transactions": 49 },
    "source": "live_clients"
  },
  "reputation": {
    "subject": "0x1111111111111111111111111111111111111111",
    "status": "available",
    "metrics": { "tx_count": 1842, "sample_transaction_count": 50, "successful_transactions": 49 },
    "source": "live_clients"
  }
}

Each detail route returns only its corresponding result inside the standard envelope; the combined example above illustrates the representative values available across the score, DNA, and reputation routes.

Token Intelligence

Get token overview

Returns a fast token overview without AI enrichment.

• Method: GET
• URL: /api/v1/token/{address}
• Header: X-API-Key

curl "https://api.sparkhood.net/api/v1/token/0x2222222222222222222222222222222222222222?chain=robinhood" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

{
  "token": { "address": "0x2222222222222222222222222222222222222222", "symbol": "TOKEN" },
  "market": { "price_usd": 0.415, "market_cap_usd": 18450000.0, "volume_24h_usd": 3214000.0 },
  "liquidity": { "liquidity_usd": 1840000.0, "locked_percent": 92.5 },
  "holders": { "holder_count": 18420, "top_10_holder_rate": 0.21 },
  "creator": { "address": "0x4444444444444444444444444444444444444444", "hold_rate": 0.018 },
  "socials": { "website": "https://example.com/token", "twitter": "@exampletoken" },
  "smart_money": { "wallet_count": 27, "net_inflow_24h_usd": 184200.0 },
  "metadata": {
    "success": true,
    "request_id": "9db893c4-22ea-4b44-9948-9784bc65d881",
    "execution_time_ms": 62.1,
    "cached": false,
    "warnings": ["Social metrics may update less frequently than market data."]
  }
}

Analyze a token

Returns the complete canonical token record and optional structured AI assessment.

• Method: GET
• URL: /api/v1/token/{address}/analysis
• Header: X-API-Key

curl "https://api.sparkhood.net/api/v1/token/0x2222222222222222222222222222222222222222/analysis?chain=robinhood&include_ai=true&limit=20" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

The analysis object contains token, market, liquidity, holders, traders, security, creator, socials, smart_money, ai, and metadata.

{
  "analysis": {
    "token": {
      "address": "0x2222222222222222222222222222222222222222",
      "chain": "robinhood",
      "name": "Robinhood Token",
      "symbol": "RHO",
      "decimals": 18
    },
    "market": {
      "price_usd": 0.415,
      "market_cap_usd": 18450000.0,
      "volume_24h_usd": 3214000.0,
      "price_change_24h": 18.4
    },
    "liquidity": { "liquidity_usd": 1840000.0, "locked_percent": 92.5 },
    "holders": { "holder_count": 18420, "top_10_holder_rate": 0.21 },
    "traders": { "active_24h": 1832, "buyers_24h": 1084, "sellers_24h": 748 },
    "security": {
      "risk_level": "medium",
      "buy_tax": 0.0,
      "sell_tax": 0.0,
      "flags": ["moderate_holder_concentration"]
    },
    "creator": {
      "address": "0x4444444444444444444444444444444444444444",
      "hold_rate": 0.018
    },
    "socials": { "website": "https://example.com/token", "twitter": "@exampletoken" },
    "smart_money": { "wallet_count": 27, "net_inflow_24h_usd": 184200.0 },
    "ai": {
      "summary": "Strong liquidity and activity with moderate holder concentration.",
      "verdict": "watch",
      "risk_level": "medium",
      "strengths": ["Deep liquidity", "Positive smart-money inflow"],
      "risks": ["Top holders control 21% of supply"],
      "market_assessment": "positive momentum",
      "liquidity_assessment": "healthy",
      "holder_assessment": "moderately concentrated",
      "smart_money_assessment": "positive inflow",
      "confidence": 0.88,
      "recommendations": ["Monitor holder concentration and liquidity changes"]
    },
    "metadata": {
      "success": true,
      "request_id": "9db893c4-22ea-4b44-9948-9784bc65d881",
      "execution_time_ms": 194.5,
      "cached": false,
      "warnings": ["Market values can change between requests."]
    }
  }
}

Market Intelligence

All Market endpoints use GET, require X-API-Key, and accept the common parameters below.

Trending tokens

• URL: /api/v1/market/trending
• Purpose: Returns ranked tokens, a summary, update timestamp, and metadata.

curl "https://api.sparkhood.net/api/v1/market/trending?chain=robinhood&interval=1h&limit=20" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Whale activity

• URL: /api/v1/market/whales
• Purpose: Returns notable wallets, market signals, a summary, and metadata.

curl "https://api.sparkhood.net/api/v1/market/whales?chain=robinhood&interval=6h&limit=20" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Smart-money activity

• URL: /api/v1/market/smart-money
• Purpose: Returns tokens and signals associated with informed market activity.

curl "https://api.sparkhood.net/api/v1/market/smart-money?chain=robinhood&interval=1h&limit=20" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Market narratives

• URL: /api/v1/market/narratives
• Purpose: Returns active market narratives and optional AI interpretation.
• Additional query: include_ai (boolean, default true).

curl "https://api.sparkhood.net/api/v1/market/narratives?chain=robinhood&interval=24h&limit=20&include_ai=true" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Capital flow

• URL: /api/v1/market/capital-flow
• Purpose: Returns inflow, outflow, asset rotation, summary, and optional AI interpretation.
• Additional query: include_ai (boolean, default true).

curl "https://api.sparkhood.net/api/v1/market/capital-flow?chain=robinhood&interval=6h&limit=20&include_ai=true" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Simplified Market response:

{
  "tokens": [
    {
      "address": "0x2222222222222222222222222222222222222222",
      "symbol": "RHO",
      "price_usd": 0.415,
      "market_cap_usd": 18450000.0,
      "volume_24h_usd": 3214000.0,
      "price_change_24h": 18.4,
      "rank": 1
    },
    {
      "address": "0x5555555555555555555555555555555555555555",
      "symbol": "HOODAI",
      "price_usd": 1.82,
      "market_cap_usd": 73100000.0,
      "volume_24h_usd": 8940000.0,
      "price_change_24h": 11.7,
      "rank": 2
    }
  ],
  "summary": {
    "count": 20,
    "gainers": 14,
    "decliners": 6,
    "total_volume_24h_usd": 42800000.0
  },
  "updated_at": 1785897600,
  "metadata": {
    "success": true,
    "chain": "robinhood",
    "interval": "1h",
    "cached": false,
    "warnings": ["Rankings can change during the selected interval."]
  }
}

Contract Intelligence

Contract Intelligence currently targets Robinhood Chain EVM contract addresses.

Get contract overview

• Method: GET
• URL: /api/v1/contract/{address}
• Header: X-API-Key
• Path parameter: address must be a 40-byte hexadecimal EVM address prefixed with 0x.

curl "https://api.sparkhood.net/api/v1/contract/0x3333333333333333333333333333333333333333" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

The response contains contract, source, verification, ownership, transactions, token, analytics, and metadata.

Analyze a contract

• Method: GET
• URL: /api/v1/contract/{address}/analysis
• Header: X-API-Key
• Query parameter: include_ai is boolean and defaults to true.

curl "https://api.sparkhood.net/api/v1/contract/0x3333333333333333333333333333333333333333/analysis?include_ai=true" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

{
  "analysis": {
    "contract": { "address": "0x3333333333333333333333333333333333333333" },
    "source": { "language": "Solidity", "compiler_version": "0.8.24" },
    "verification": { "verified": true, "status": "verified", "proxy": false },
    "ownership": {
      "owner": "0x4444444444444444444444444444444444444444",
      "renounced": false,
      "multisig": true
    },
    "security": {
      "risk_level": "low",
      "findings": ["Source code verified", "No proxy upgrade path detected"]
    },
    "transactions": { "total": 182441, "last_24h": 2387 },
    "token": { "name": "Robinhood Token", "symbol": "RHO", "holders": 18420 },
    "analytics": { "active_addresses_24h": 1832, "transfer_volume_24h": 4821900.0 },
    "ai": {
      "summary": "Verified non-proxy contract with multisig ownership.",
      "verdict": "low observed risk",
      "risk_level": "low",
      "findings": ["Verified source", "Active usage"],
      "risks": ["Owner privileges remain active"],
      "ownership_assessment": "multisig controlled",
      "upgradeability_assessment": "not upgradeable",
      "activity_assessment": "high activity",
      "confidence": 0.91,
      "recommendations": ["Monitor owner-initiated transactions"]
    },
    "metadata": {
      "success": true,
      "request_id": "37c44761-4340-4bf3-a41d-70d258072ab2",
      "execution_time_ms": 211.3,
      "cached": false,
      "warnings": ["Security observations are informational and are not an audit."]
    }
  }
}

Swap Intelligence

Swap endpoints plan or simulate an operation; they do not broadcast transactions.

Get a quote

• Method: POST
• URL: /api/v1/swap/quote
• Headers: X-API-Key, Content-Type: application/json

curl -X POST "https://api.sparkhood.net/api/v1/swap/quote" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"token_in":"0x1111111111111111111111111111111111111111","token_out":"0x2222222222222222222222222222222222222222","amount":"1000000000000000000","slippage_bps":50}'

{
  "success": true,
  "data": {
    "token_in": "0x1111111111111111111111111111111111111111",
    "token_out": "0x2222222222222222222222222222222222222222",
    "amount_in": "1000000000000000000",
    "estimated_amount_out": "2398450000000000000",
    "minimum_amount_out": "2386457750000000000",
    "price_impact_percent": 0.18,
    "slippage_bps": 50,
    "route": ["RHO", "USDC", "TOKEN"]
  },
  "request_id": "a6ff12ab-d6ae-4ed0-942f-08e4bf1de1a2"
}

Simulate a swap

• Method: POST
• URL: /api/v1/swap/simulate
• Headers: X-API-Key, Content-Type: application/json
• Body: Same fields as quote, plus optional sender string.

curl -X POST "https://api.sparkhood.net/api/v1/swap/simulate" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"token_in":"0x1111111111111111111111111111111111111111","token_out":"0x2222222222222222222222222222222222222222","amount":"1000000000000000000","slippage_bps":50,"sender":"0x3333333333333333333333333333333333333333"}'

Both endpoints return the standard success, data, and request_id envelope.

User API keys

API-key management is administrative in the current API. These routes require X-Master-Key, not X-API-Key.

Create an API key

• Method: POST
• URL: /api/v1/user/api-keys
• Headers: X-Master-Key, Content-Type: application/json
• Body: address (EVM wallet address) and name (1–100 characters).

curl -X POST "https://api.sparkhood.net/api/v1/user/api-keys" \
  -H "X-Master-Key: your-administrative-secret" \
  -H "Content-Type: application/json" \
  -d '{"address":"0x1111111111111111111111111111111111111111","name":"Production Agent"}'

{
  "api_key": "rh_live_xxxxxxxxx",
  "prefix": "rh_live_xxxx",
  "created_at": "2026-08-05T10:30:00Z"
}

Copy api_key immediately. It cannot be retrieved later.

List keys for an address

• Method: GET
• URL: /api/v1/user/api-keys/{address}
• Header: X-Master-Key

curl "https://api.sparkhood.net/api/v1/user/api-keys/0x1111111111111111111111111111111111111111" \
  -H "X-Master-Key: your-administrative-secret"

The response is an array containing id, prefix, name, created_at, last_used_at, and active. Plaintext keys are never listed.

Update an API key

• Method: PATCH
• URL: /api/v1/user/api-keys/{key_id}
• Headers: X-Master-Key, Content-Type: application/json
• Body: optional name and/or is_active.

curl -X PATCH "https://api.sparkhood.net/api/v1/user/api-keys/KEY_ID" \
  -H "X-Master-Key: your-administrative-secret" \
  -H "Content-Type: application/json" \
  -d '{"name":"Renamed Agent","is_active":true}'

Revoke an API key

• Method: DELETE
• URL: /api/v1/user/api-keys/{key_id}
• Header: X-Master-Key

curl -X DELETE "https://api.sparkhood.net/api/v1/user/api-keys/KEY_ID" \
  -H "X-Master-Key: your-administrative-secret"

Revocation is represented by an inactive key record. Requests using that key are rejected.

User Activity and Analysis History

User Activity endpoints resolve their wallet owner directly from X-API-Key. Do not send an address query or path parameter. Administrative master credentials cannot be used because they are not associated with a user wallet.

Successful Wallet, Token, Contract, and Market analysis responses are recorded automatically. History contains the final public JSON response—not upstream or intermediate data—and is isolated by the wallet owner associated with the authenticated key.

Note: Analysis history is separate from Wallet Intelligence transaction history. It records API analyses requested by a user; it does not represent on-chain wallet transactions.

Get recent user conversations

• Method: GET
• URL: /api/v1/user/chat
• Header: X-API-Key
• Parameters: None

Returns at most 20 conversations for the authenticated owner, ordered by most recent activity. Each summary contains id, title, last_message, updated_at, and message_count.

curl "https://api.sparkhood.net/api/v1/user/chat" \
  -H "X-API-Key: rh_live_xxxxxxxxx"

Get the frontend dashboard

• Method: GET
• URL: /api/v1/user/dashboard
• Header: X-API-Key
• Parameters: None

curl "https://api.sparkhood.net/api/v1/user/dashboard" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

{
  "wallet": {
    "address": "0x1111111111111111111111111111111111111111",
    "chain": "robinhood",
    "balance_usd": 12543.82,
    "pnl_usd": 2345.71,
    "pnl_percent": 23.0
  },
  "usage": {
    "today": 4,
    "this_week": 18,
    "this_month": 47,
    "total": 126
  },
  "api_keys": {
    "active": 2,
    "remaining": 1,
    "max": 3
  },
  "latest_analysis": {
    "id": "b4474052-428c-496d-b842-a92cec154cbe",
    "analysis_type": "wallet",
    "target": "0x7777777777777777777777777777777777777777",
    "summary": "Analyze wallet 0x7777777777777777777777777777777777777777",
    "created_at": "2026-08-05T14:22:31Z",
    "request_id": "5cf93486-00e3-48f9-9c91-d4b1622161ae",
    "response": {
      "analysis": {
        "wallet": {
          "address": "0x7777777777777777777777777777777777777777",
          "chain": "robinhood",
          "score": 78
        },
        "metadata": {
          "success": true,
          "request_id": "5cf93486-00e3-48f9-9c91-d4b1622161ae"
        }
      }
    }
  },
  "recent_history": [
    {
      "id": "b4474052-428c-496d-b842-a92cec154cbe",
      "analysis_type": "wallet",
      "target": "0x7777777777777777777777777777777777777777",
      "summary": "Analyze wallet 0x7777777777777777777777777777777777777777",
      "created_at": "2026-08-05T14:22:31Z",
      "status": "success"
    }
  ],
  "metadata": {
    "generated_at": "2026-08-05T14:24:00Z",
    "request_id": "7149a9eb-e97a-445c-9c4d-d2684619f06b"
  }
}

This is the recommended initial-load endpoint for the frontend dashboard. Usage counters use UTC calendar boundaries. latest_analysis is null and recent_history is empty when the owner has no history. Recent records never include their stored response payload.

Get detailed usage statistics

• Method: GET
• URL: /api/v1/user/usage
• Header: X-API-Key
• Parameters: None

Returns owner-scoped analysis counts for the current UTC day, week, month, and all time. This endpoint is suitable for dashboard analytics and is designed to accommodate future billing and quota information.

curl "https://api.sparkhood.net/api/v1/user/usage" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

{
  "today": {
    "requests": 28,
    "wallet": 10,
    "token": 8,
    "market": 6,
    "contract": 4,
    "swap": 0
  },
  "this_week": {
    "requests": 142,
    "wallet": 56,
    "token": 41,
    "market": 25,
    "contract": 20,
    "swap": 0
  },
  "this_month": {
    "requests": 581,
    "wallet": 201,
    "token": 176,
    "market": 104,
    "contract": 100,
    "swap": 0
  },
  "total": {
    "requests": 1832,
    "wallet": 712,
    "token": 603,
    "market": 287,
    "contract": 230,
    "swap": 0
  },
  "quota": null,
  "metadata": {
    "generated_at": "2026-08-05T14:24:00Z",
    "request_id": "7149a9eb-e97a-445c-9c4d-d2684619f06b"
  }
}

Usage aggregates are cached per owner for 30 seconds. A successful new analysis automatically invalidates the owner's cached usage. Request-specific metadata is generated for every call and is not reused from cache.

Get the authenticated user's wallet

• Method: GET
• URL: /api/v1/user/wallet
• Header: X-API-Key
• Parameters: None

curl "https://api.sparkhood.net/api/v1/user/wallet" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

{
  "wallet": {
    "address": "0x1111111111111111111111111111111111111111",
    "chain": "robinhood",
    "balance_usd": 12543.82,
    "pnl_usd": 2345.71,
    "pnl_percent": 23.0
  },
  "metadata": {
    "success": true,
    "request_id": "c2cb999d-53af-45ea-9097-7a9f498d9bc0",
    "execution_time_ms": 83.4,
    "cached": false,
    "warnings": ["Portfolio values reflect the latest available intelligence snapshot."]
  }
}

This endpoint reuses Wallet Intelligence and returns only its simplified portfolio overview. It does not create an analysis-history record.

List analysis history

• Method: GET
• URL: /api/v1/user/history
• Header: X-API-Key

curl "https://api.sparkhood.net/api/v1/user/history?limit=20&offset=0" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

[
  {
    "id": "b4474052-428c-496d-b842-a92cec154cbe",
    "analysis_type": "wallet",
    "target": "0x7777777777777777777777777777777777777777",
    "summary": "Analyze wallet 0x7777777777777777777777777777777777777777",
    "created_at": "2026-08-05T14:22:31Z",
    "request_id": "5cf93486-00e3-48f9-9c91-d4b1622161ae",
    "response": {
      "analysis": {
        "wallet": {
          "address": "0x7777777777777777777777777777777777777777",
          "chain": "robinhood",
          "score": 78
        },
        "portfolio": {
          "total_value_usd": 12543.82,
          "total_profit_usd": 2345.71
        },
        "metadata": {
          "success": true,
          "request_id": "5cf93486-00e3-48f9-9c91-d4b1622161ae",
          "cached": false
        }
      }
    }
  }
]

Records are ordered newest first. response is the same final JSON object returned by the original analysis request. Offset pagination applies only to this endpoint; general Intelligence pagination remains reserved for future implementation.

Get the latest analysis

• Method: GET
• URL: /api/v1/user/latest-analysis
• Header: X-API-Key
• Parameters: None

curl "https://api.sparkhood.net/api/v1/user/latest-analysis" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

{
  "analysis": {
    "id": "b4474052-428c-496d-b842-a92cec154cbe",
    "analysis_type": "token",
    "target": "0x2222222222222222222222222222222222222222",
    "summary": "Analyze token 0x2222222222222222222222222222222222222222",
    "created_at": "2026-08-05T14:31:08Z",
    "request_id": "6541ae9c-e441-42ec-bd19-a436827d0f84",
    "response": {
      "analysis": {
        "token": {
          "address": "0x2222222222222222222222222222222222222222",
          "symbol": "RHO"
        },
        "metadata": {
          "success": true,
          "request_id": "6541ae9c-e441-42ec-bd19-a436827d0f84",
          "cached": false
        }
      }
    }
  }
}

The endpoint returns 404 Not Found with code not_found when the authenticated owner has no recorded analysis.

Skill discovery

List skills

• Method: GET
• URL: /api/v1/skills
• Authentication: None
• Purpose: Lists registered AI-callable skills and their input/output metadata.

curl "https://api.sparkhood.net/api/v1/skills"

Get skill metadata

• Method: GET
• URL: /api/v1/skills/{name}
• Authentication: None
• Path parameter: Registered skill name.

curl "https://api.sparkhood.net/api/v1/skills/get_wallet"

These endpoints are intended for capability discovery. Consumers should not assume a skill is registered until it appears in the discovery response.

Health monitoring

Health check

• Method: GET
• URL: /health
• Authentication: None

curl "https://api.sparkhood.net/health"

{
  "status": "healthy",
  "intelligence_engine": {
    "configured": true,
    "status": "ready"
  }
}

The exact health components may vary by deployment. Treat top-level status as liveness and component status as readiness.

Diagnostic check

• Method: GET
• URL: /debug/gmgn-cli
• Authentication: None when enabled
• Availability: Development and diagnostic deployments only (DEBUG=true). Production deployments must not expose debug routes.

The path is retained for compatibility. Its response reports whether the external intelligence runtime is available and configured. Applications must not depend on this diagnostic endpoint for normal operation.

Common Examples

The following requests use the production placeholder. Set API_BASE_URL and replace all example credentials and addresses before use.

Analyze a wallet

curl "https://api.sparkhood.net/api/v1/wallet/0x1111111111111111111111111111111111111111/analysis?chain=robinhood&include_ai=true&include_activity=true&include_created_tokens=true" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

Use analysis.portfolio for portfolio totals and performance; Portfolio Intelligence is integrated into Wallet Intelligence.

Analyze a token

curl "https://api.sparkhood.net/api/v1/token/0x2222222222222222222222222222222222222222/analysis?chain=robinhood&include_ai=true&limit=20" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

Set include_ai=false when deterministic token facts are sufficient and lower analysis latency is preferred.

Get trending tokens

curl "https://api.sparkhood.net/api/v1/market/trending?chain=robinhood&interval=1h&limit=20" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

Use a supported interval to align rankings with your trading or monitoring horizon.

Analyze a contract

curl "https://api.sparkhood.net/api/v1/contract/0x3333333333333333333333333333333333333333/analysis?include_ai=true" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Accept: application/json"

Contract findings are intelligence signals, not a replacement for an independent security audit.

Get a swap quote

curl -X POST "https://api.sparkhood.net/api/v1/swap/quote" \
  -H "X-API-Key: rh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"token_in":"0x1111111111111111111111111111111111111111","token_out":"0x2222222222222222222222222222222222222222","amount":"1000000000000000000","slippage_bps":50}'

Quotes are informational and are not broadcast as transactions.

SDK Examples

There is no required SDK. Any HTTP client that can send JSON and custom headers can call the API.

Python with requests

import os

import requests

base_url = os.environ.get("ROBINHOOD_API_URL", "https://api.sparkhood.net")
api_key = os.environ["ROBINHOOD_API_KEY"]

response = requests.get(
    f"{base_url}/api/v1/market/trending",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    params={"chain": "robinhood", "interval": "1h", "limit": 20},
    timeout=30,
)
response.raise_for_status()
payload = response.json()
print(payload["tokens"][0]["symbol"])

JavaScript with fetch

const baseUrl = process.env.ROBINHOOD_API_URL ?? "https://api.sparkhood.net";
const response = await fetch(
  `${baseUrl}/api/v1/token/0x2222222222222222222222222222222222222222/analysis?chain=robinhood&include_ai=true&limit=20`,
  {
    headers: {
      "X-API-Key": process.env.ROBINHOOD_API_KEY,
      Accept: "application/json",
    },
  },
);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`${error.error?.code}: ${error.error?.message}`);
}

const payload = await response.json();
console.log(payload.analysis.token.symbol);

Note: Keep API calls in trusted server-side code. Do not expose a user API key in browser-delivered JavaScript.

Supported chains

“Supported” means the public endpoint accepts the chain identifier. Data availability may vary by capability and deployment. Contract endpoints currently accept no chain selector and use Robinhood Chain.

Pagination

General Intelligence pagination is reserved for future implementation.

Analysis history supports documented limit and offset pagination. Other list-oriented Intelligence endpoints use bounded query parameters such as limit; they do not return page numbers, continuation tokens, or general-purpose cursors as a stable public contract. Do not send undocumented pagination parameters.

Rate limits

Public client rate-limit policy and quota headers are reserved for future implementation. Individual intelligence sources may still return 429 Too Many Requests. Clients should implement bounded exponential backoff with jitter and avoid retrying validation or authentication failures.

Caching

Intelligence responses may be cached. Redis is optional and recommended for production, where multiple application processes benefit from a shared cache. Development works without Redis: when CACHE_ENABLED=true and REDIS_URL is empty, the server uses an in-memory cache. If a configured Redis instance is unavailable during startup, the server automatically falls back to the in-memory cache and continues serving requests. Set CACHE_ENABLED=false to disable caching.

CACHE_ENABLED=true
REDIS_URL=

GET /health reports the active provider and whether caching is enabled. When present, metadata.cached indicates whether an Intelligence response used cached data. Cache durations are deployment configuration and are not part of the stable public contract.

To avoid unnecessary work:

• Reuse recent results when your freshness requirements allow it.
• Do not poll analysis endpoints more frequently than the underlying use case requires.
• Treat metadata as request context, not intelligence data.

Retries and timeouts

• Set a finite client timeout suitable for an intelligence aggregation request.
• Retry only idempotent GET requests automatically.
• Retry 429 and transient 5xx responses with exponential backoff and jitter.
• Cap attempts and total elapsed time.
• Do not retry 400, 401, 403, 404, 409, or 422 without changing the request.
• Reuse the same X-Request-ID across retries for traceability when appropriate.

API-key security best practices

• Store API keys in a secret manager or protected environment variable.
• Never embed keys in client-side code, source control, logs, URLs, or error reports.
• Use separate keys for each application and environment.
• Rotate keys regularly and immediately after suspected exposure.
• Revoke unused keys and monitor last_used_at through administrative tooling.
• Restrict the master key to trusted administrative systems.
• Send credentials only over HTTPS outside local development.

Integration checklist

1. Obtain a user API key from an authorized administrator.
2. Configure the production base URL and store the key securely.
3. Send X-API-Key on protected intelligence requests.
4. Set timeouts and bounded retry behavior.
5. Parse skill-specific canonical objects and retain metadata.warnings.
6. Log the response X-Request-ID without logging credentials.
7. Use /health for liveness and /api/v1/skills for capability discovery.

FAQ

Why do I receive 401 Unauthorized?

The X-API-Key header may be missing, misspelled, invalid, inactive, or revoked. Confirm that you are sending the user key in a header—not a query parameter—and that an administrator has not deactivated it. Administrative routes instead require X-Master-Key.

Why is AI analysis null?

AI analysis is optional. It is null when include_ai=false, when AI configuration is unavailable, or when an enrichment cannot complete while the underlying intelligence response remains usable. Inspect metadata.warnings for non-fatal context.

How long is data cached?

Cache duration varies by Intelligence category and deployment configuration. Use metadata.cached to determine whether a response used cached data. Cache TTL values are not a stable public API guarantee.

Can one API key be shared?

Technically, the same active key can authenticate more than one request source, but sharing is strongly discouraged. Use a separate key per application and environment so each credential can be rotated or revoked independently.

How many API keys can I create?

An address can have up to three active API keys. Creating or reactivating another key at that limit returns 409 Conflict. Revoke or deactivate an unused key before adding another.

What chains are supported?

Wallet, Token, and Market Intelligence accept robinhood, eth, bsc, base, and sol. Contract Intelligence currently targets Robinhood Chain EVM addresses and has no chain query parameter. Swap availability outside Robinhood Chain is deployment-dependent.

Should I retry a failed request?

Retry idempotent requests only for 429 and transient 5xx failures. Use bounded exponential backoff with jitter. Correct the request or credentials before retrying 4xx failures other than 429.

Where can I find the request ID?

Read the X-Request-ID response header. Standard envelopes and canonical metadata also expose it in JSON. Include the identifier—never the API key—when reporting an issue.

Is a contract risk result a security audit?

No. Contract Intelligence summarizes observed verification, ownership, activity, and security signals. It does not replace source review, formal verification, or a professional audit.

Changelog

1.0.0 — Initial Release

• Wallet Intelligence with integrated Portfolio Intelligence
• Token, Market, and Contract Intelligence
• Swap quote and simulation
• User API-key administration
• User wallet context and persistent analysis history
• Skill discovery and health monitoring

Versioning policy

Documentation releases follow Semantic Versioning (MAJOR.MINOR.PATCH):

Future releases may add optional response fields, metadata, supported capabilities, or new endpoints without removing existing v1 behavior. Integrations should tolerate unknown fields and should not rely on object key ordering.

When a breaking change is necessary, it will be introduced through a new versioned API contract and accompanied by migration guidance. Deprecation notices will identify the affected behavior, recommended replacement, and planned retirement window when applicable.