AI-TAMSA

Developers

API Documentation

Complete reference for the Xphere blockchain APIs — GraphQL, REST, SSE streaming, webhooks, oracle data, AI, and more.

Base URL: https://beta.tamsa.io12 API categories98+ endpoints
Authentication

All API requests require an API key passed via the X-API-Key header. Create keys in Settings > API Keys. Public endpoints (blocks, transactions) also work without a key at reduced rate limits.

Example

curl -H "X-API-Key: xp-pro-abc123..." \
  https://beta.tamsa.io/api/blocks?count=5

Notes

  • -Free: 100 req/day, 1 API key
  • -Pro: 10,000 req/day, 5 API keys
  • -Enterprise: 100,000 req/day, 20 API keys
  • -Rate limits are per API key, sliding window
GraphQL API
Recommended

Flexible query language with precise field selection, pagination, filtering, and nested relationships. Supports blocks, transactions, events, tokens, addresses, custom events, and network stats.

POST
/api/graphqlGraphQL endpoint (also accepts GET for queries)

Example

// Query latest blocks with transactions
const res = await fetch("https://beta.tamsa.io/api/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-key",
  },
  body: JSON.stringify({
    query: `{
      blocks(limit: 5) {
        number
        hash
        timestamp
        miner
        txCount
        gasUsed
      }
      networkStats {
        blockHeight
        avgBlockTime
        avgTps
        totalTransactions
      }
    }`
  })
});

// Query transactions with filters
const txQuery = `{
  transactions(
    address: "0x...",
    txType: "contract_call",
    limit: 20
  ) {
    hash
    from
    to
    value
    methodName
    status
    timestamp
    events {
      eventName
      address
      decodedArgs
    }
  }
}`;

// Query token holders
const tokenQuery = `{
  token(address: "0x...") {
    name
    symbol
    totalSupply
    holderCount
    holders(limit: 10) {
      address
      balance
    }
  }
}`;

// Custom indexed events
const customQuery = `{
  customEvents(
    contractAddress: "0x...",
    eventName: "Transfer",
    limit: 50
  ) {
    txHash
    blockNumber
    eventName
    decodedArgs
    timestamp
  }
}`;

Notes

  • -Interactive playground at /playground
  • -Supports Relay-style cursor pagination
  • -DataLoader prevents N+1 queries
  • -Max query depth: 10, max complexity: 1000
Blocks

Query block data. Returns indexed data first, falls back to RPC if the indexer is behind.

GET
/api/blocksList blocks— params: count (1-50), page
GET
/api/blocks/:numberBlock detail by number

Example

// List recent blocks
const res = await fetch("https://beta.tamsa.io/api/blocks?count=10");
const { blocks, total, page } = await res.json();

// Block detail
const block = await fetch("https://beta.tamsa.io/api/blocks/33000000")
  .then(r => r.json());

Response

{
  "number": 33000000,
  "hash": "0xabc...",
  "parentHash": "0xdef...",
  "timestamp": 1709712000,
  "miner": "0x1234...",
  "gasUsed": "1200000",
  "gasLimit": "30000000",
  "baseFeePerGas": "25000000000",
  "txCount": 12,
  "size": 4567
}
Transactions

Query transaction data with optional filters by sender, recipient, or transaction type.

GET
/api/transactionsList transactions— params: count (1-100), page, type, from, to
GET
/api/transactions/:hashTransaction detail
GET
/api/transactions/:hash/internalInternal transactions (traces)

Example

// Filter by sender
const txs = await fetch(
  "https://beta.tamsa.io/api/transactions?from=0x...&count=20"
).then(r => r.json());

// Transaction detail with interpretation
const tx = await fetch("https://beta.tamsa.io/api/transactions/0xabc...")
  .then(r => r.json());

// Internal transactions
const traces = await fetch(
  "https://beta.tamsa.io/api/transactions/0xabc.../internal"
).then(r => r.json());

Response

{
  "hash": "0xabc...",
  "blockNumber": 33000000,
  "from": "0x1234...",
  "to": "0x5678...",
  "value": "1000000000000000000",
  "valueXP": "1.0",
  "gasPrice": "25000000000",
  "gasUsed": "21000",
  "methodId": "0xa9059cbb",
  "methodName": "transfer",
  "status": 1,
  "timestamp": 1709712000,
  "type": "token_transfer"
}
Addresses

Address information including balance, transaction history, token holdings, and relationship graphs.

GET
/api/addresses/:addressAddress info (balance, tx count, contract status)
GET
/api/addresses/:address/profileAI-generated address profileauth
GET
/api/addresses/:address/graphRelationship graph (CIOH clustering)
GET
/api/addresses/:address/exportExport transaction history (CSV)

Example

// Address info
const info = await fetch("https://beta.tamsa.io/api/addresses/0x1234...")
  .then(r => r.json());
// { address, balance, balanceXP, transactionCount, isContract }

// Relationship graph
const graph = await fetch("https://beta.tamsa.io/api/addresses/0x1234.../graph")
  .then(r => r.json());
// { nodes: [...], edges: [...], clusters: [...] }
Tokens

ERC-20 and ERC-721 token data including holders, transfers, and metadata.

GET
/api/tokensToken list (sorted by transfer count)— params: count (1-100), page
GET
/api/tokens/:addressToken detail (holders, transfers)
GET
/api/nft/:address/:tokenIdNFT metadata

Example

// Token list
const tokens = await fetch("https://beta.tamsa.io/api/tokens?count=20")
  .then(r => r.json());

// Token detail
const token = await fetch("https://beta.tamsa.io/api/tokens/0x...")
  .then(r => r.json());
// { name, symbol, decimals, totalSupply, holderCount, holders, transfers }
Smart Contracts

Contract analysis, verification, read/write calls, and interaction statistics.

GET
/api/contracts/:addressAI contract analysisauth
POST
/api/contracts/:address/callRead contract function
POST
/api/contracts/:address/verifyVerify source code
GET
/api/contracts/:address/creatorContract creator
GET
/api/contracts/:address/statsInteraction statistics
GET
/api/contracts/:address/proxyProxy implementation

Example

// Read contract function (e.g., ERC-20 balanceOf)
const result = await fetch("https://beta.tamsa.io/api/contracts/0x.../call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    functionName: "balanceOf",
    args: ["0x1234..."],
  })
}).then(r => r.json());

// Verify contract
await fetch("https://beta.tamsa.io/api/contracts/0x.../verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    sourceCode: "// SPDX-License-Identifier: MIT...",
    contractName: "MyToken",
    compilerVersion: "v0.8.20",
    optimizationRuns: 200,
  })
});
Oracle & Price Data
Oraxl

Real-time cryptocurrency prices from the Oraxl on-chain oracle. 14 price feeds (XP, BTC, ETH, SOL, etc.) sourced from 4-5 exchanges with median aggregation, circuit breaker protection, and TWAP.

GET
/api/priceXP/USDT price (with optional history)— params: history=true

Example

// Get current XP price with exchange breakdown
const price = await fetch("https://beta.tamsa.io/api/price")
  .then(r => r.json());

// With price history (last 20 rounds)
const priceWithHistory = await fetch("https://beta.tamsa.io/api/price?history=true")
  .then(r => r.json());

Response

{
  "price": 0.0063305,
  "priceRaw": "633050",
  "roundId": 175,
  "updatedAt": 1709712000,
  "pair": "XP/USDT",
  "oracle": "0x6e32Ea5a...",
  "confidence": 0.00002,
  "sources": 4,
  "exchanges": [
    { "name": "MEXC", "price": 0.00634 },
    { "name": "XT.com", "price": 0.00632 },
    { "name": "LBank", "price": 0.00633 },
    { "name": "BingX", "price": 0.00634 }
  ]
}

Notes

  • -14 pairs: XP, BTC, ETH, SOL, BNB, XRP, ADA, AVAX, DOT, LINK, UNI, DOGE, AAVE, ARB, OP (all /USDT)
  • -On-chain contracts: Chainlink AggregatorV3 compatible (latestRoundData, getRoundData)
  • -FeedRegistry: 0x175f9b1f... — getAllFeeds() to discover all feeds
  • -GenericDataOracle: 0x92a1feBB... — Fear & Greed, BTC Dominance, Market Cap, ETH Gas
  • -Circuit breaker: rejects updates with >20% price deviation
  • -TWAP: 100-round time-weighted average
  • -Confidence: half the spread between exchange prices
Real-time Streaming (SSE)
WebSocket Alternative

Server-Sent Events for real-time blockchain data. Powered by PostgreSQL LISTEN/NOTIFY with sub-second latency. Automatically reconnects on disconnect.

SSE
/api/stream/blocksNew blocks as they are mined
SSE
/api/stream/transactionsNew transactions (filterable)— params: from, to, txType
SSE
/api/stream/eventsContract events (filterable)— params: address, eventName

Example

// Stream new blocks
const blocks = new EventSource("https://beta.tamsa.io/api/stream/blocks");
blocks.onmessage = (e) => {
  const block = JSON.parse(e.data);
  console.log(`Block #${block.number}: ${block.txCount} txs`);
};

// Stream transactions from a specific address
const txs = new EventSource(
  "https://beta.tamsa.io/api/stream/transactions?from=0x1234..."
);
txs.onmessage = (e) => {
  const tx = JSON.parse(e.data);
  console.log(`TX: ${tx.hash} | ${tx.valueXP} XP`);
};

// Stream Transfer events from a contract
const events = new EventSource(
  "https://beta.tamsa.io/api/stream/events?address=0x...&eventName=Transfer"
);
events.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log(`${event.eventName}: ${JSON.stringify(event.args)}`);
};

// curl example
// curl -N "https://beta.tamsa.io/api/stream/blocks"

Notes

  • -Heartbeat every 30 seconds to keep connection alive
  • -Automatic reconnection with EventSource API
  • -Filter transactions by from/to address or txType
  • -Filter events by contract address or event name
  • -Powered by pg LISTEN/NOTIFY — sub-second latency
Custom Indexing

Register contract ABIs to automatically decode and index custom events. The indexer matches events against registered ABIs in real-time, storing decoded arguments for fast querying.

GET
/api/custom-indexesList your custom indexesauth
POST
/api/custom-indexesCreate a new custom indexauth
GET
/api/custom-indexes/:idIndex detailauth
PATCH
/api/custom-indexes/:idUpdate (name, status)auth
DELETE
/api/custom-indexes/:idRemove an indexauth
POST
/api/custom-indexes/:id/abisRegister ABI (auto-extracts event signatures)auth
GET
/api/custom-indexes/:id/eventsQuery decoded events— params: eventName, contractAddress, limit, offsetauth

Example

// 1. Create a custom index
const idx = await fetch("https://beta.tamsa.io/api/custom-indexes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-key",
  },
  body: JSON.stringify({
    name: "My DEX Events",
    description: "Track swap events on XphereDEX"
  })
}).then(r => r.json());

// 2. Register the contract ABI
await fetch(`https://beta.tamsa.io/api/custom-indexes/${idx.id}/abis`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-key",
  },
  body: JSON.stringify({
    contractAddress: "0xDEXAddress...",
    abi: [/* ERC-20 or custom ABI */]
  })
});

// 3. Query indexed events
const events = await fetch(
  `https://beta.tamsa.io/api/custom-indexes/${idx.id}/events?eventName=Swap&limit=50`,
  { headers: { "X-API-Key": "your-key" } }
).then(r => r.json());

Notes

  • -ABI is validated using ethers.js Interface — invalid ABIs are rejected
  • -Event signatures are auto-extracted from the ABI
  • -Events are decoded in real-time as blocks are indexed
  • -Batch processing: 500 events per chunk
  • -Also queryable via GraphQL: customEvents query
Webhooks (Event Subscriptions)

Subscribe to on-chain events and receive HTTP webhook notifications. Filter by contract address, event name, or topic hash. Includes retry with exponential backoff and delivery tracking.

GET
/api/subscriptionsList your subscriptionsauth
POST
/api/subscriptionsCreate a subscriptionauth
GET
/api/subscriptions/:idDetail + recent deliveriesauth
PATCH
/api/subscriptions/:idPause/resumeauth
DELETE
/api/subscriptions/:idRemoveauth
POST
/api/subscriptions/:id/testSend test webhookauth

Example

// Create a subscription for Transfer events
const sub = await fetch("https://beta.tamsa.io/api/subscriptions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-key",
  },
  body: JSON.stringify({
    name: "Whale Transfers",
    webhookUrl: "https://your-server.com/webhook",
    filters: {
      address: "0xTokenAddress...",
      eventName: "Transfer"
    },
    headers: {
      "X-Webhook-Secret": "your-secret"
    }
  })
}).then(r => r.json());

// Test the webhook
await fetch(`https://beta.tamsa.io/api/subscriptions/${sub.id}/test`, {
  method: "POST",
  headers: { "X-API-Key": "your-key" },
});

Response

// Webhook payload your server receives:
{
  "event": "subscription_match",
  "subscription": {
    "id": "sub_abc123",
    "name": "Whale Transfers"
  },
  "data": {
    "txHash": "0xabc...",
    "blockNumber": 33000000,
    "address": "0xTokenAddress...",
    "eventName": "Transfer",
    "timestamp": 1709712000,
    "decodedArgs": {
      "from": "0x1234...",
      "to": "0x5678...",
      "value": "5000000000000000000000"
    }
  },
  "meta": {
    "sentAt": "2026-03-06T12:00:00.000Z"
  }
}

Notes

  • -Webhook URL must be HTTPS
  • -Retry with exponential backoff: 1s, 2s, 4s, ... max 5min, up to 5 retries
  • -Delivery log tracks status codes, response times, and errors
  • -Limits: Free 5, Pro 25, Enterprise 100 subscriptions
  • -Filters: address, topic0, eventName (at least one required)
Network & Analytics

Network statistics, mining data, supply information, and analytics endpoints.

GET
/api/networkNetwork stats (block height, gas price, TPS)
GET
/api/statsAnalytics (daily TX, gas, volume trends)
GET
/api/miningMining overview (top miners, rewards, hashrate)
GET
/api/supplySupply breakdown (minted, distribution, halving)
GET
/api/top-accountsTop accounts by transaction count
GET
/api/dashboardDashboard metrics (aggregated)
GET
/api/defiDeFi analytics (TVL, risk scoring)
GET
/api/labelsAddress labels (exchanges, validators, whales)
GET
/api/searchSearch autocomplete (tokens + labels)— params: q

Example

// Network stats
const stats = await fetch("https://beta.tamsa.io/api/network").then(r => r.json());
// { blockNumber, gasPrice, tps, latestBlock }

// Supply breakdown
const supply = await fetch("https://beta.tamsa.io/api/supply").then(r => r.json());
// { totalSupply, totalMinted, breakdown: { miners, union, foundation } }

// Mining leaderboard
const mining = await fetch("https://beta.tamsa.io/api/mining").then(r => r.json());
// { topMiners, networkStats, hourlyProduction, rewardEstimates }

// Search
const results = await fetch("https://beta.tamsa.io/api/search?q=uni")
  .then(r => r.json());
AI Chat & MCP
AI-Powered

AI-powered blockchain assistant with 32 tools for querying blocks, transactions, addresses, mining, oracle data, and more. Also available as an MCP server for integration with external AI agents (Claude Desktop, etc.).

POST
/api/chatAI chat (streaming response, 32 blockchain tools)
POST
/api/mcpMCP server endpoint for external AI agents
POST
/api/ai/tx-analysisDeep AI transaction analysis

Example

// AI Chat (streaming)
const res = await fetch("https://beta.tamsa.io/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    messages: [
      { role: "user", content: "Show me the top 5 miners and their rewards" }
    ]
  })
});
// Returns streaming response (Vercel AI SDK format)

// MCP Server — configure in Claude Desktop:
// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "xphere": {
      "url": "https://beta.tamsa.io/api/mcp"
    }
  }
}

// AI Transaction Analysis
const analysis = await fetch("https://beta.tamsa.io/api/ai/tx-analysis", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ txHash: "0xabc..." })
}).then(r => r.json());

Notes

  • -32 AI tools: blocks, transactions, addresses, mining, tokens, oracle, market data, wallet profiles, and more
  • -Streaming responses via Vercel AI SDK
  • -Rate limit: 15 requests/minute per IP
  • -Max 50 messages per conversation
  • -MCP: Model Context Protocol — lets Claude Desktop, Cursor, etc. query Xphere data
  • -Available tools include: get_xp_price, get_oracle_feeds, get_market_data, get_wallet_profile, get_top_miners, get_union_members, and more