Orama API Documentation

Overview

Orama provides a RESTful API that allows developers to integrate Orama's powerful blockchain analytics and risk assessment capabilities into their own applications. This documentation covers the available endpoints, authentication methods, request parameters, and response formats.

Authentication

All API requests require authentication using an API key.

Headers:

Authorization: Bearer YOUR_API_KEY

To obtain an API key, please contact [e-mail].

Base URL

https://api.orama.xyz/v1

Rate Limits

• Free tier: 100 requests per day

• Basic tier: 1,000 requests per day

• Premium tier: 10,000 requests per day

• Enterprise tier: Custom limits available

Risk Assessment API

Get Token Risk Assessment

Retrieve comprehensive risk assessment for a specific token.

Endpoint: /risk/token/{address}

Method: GET

URL Parameters:

• address (required) - The token address to analyze

Query Parameters:

• include_details (optional) - Boolean (default: false) - Include detailed breakdown of risk factors

• chain (optional) - String (default: "solana") - Blockchain to analyze (solana, ethereum)

Example Request:

curl -X GET "https://api.orama.xyz/v1/risk/token/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU?include_details=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "success": true,
  "data": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "name": "Example Token",
    "symbol": "EXT",
    "risk_score": 78,
    "risk_level": "medium",
    "updated_at": "2023-06-15T14:22:31Z",
    "summary": "This token presents a medium level of risk primarily due to high concentration of tokens in few wallets and limited trading history.",
    "risk_factors": {
      "contract_security": {
        "score": 85,
        "level": "low",
        "details": [
          {
            "factor": "code_audit",
            "value": true,
            "impact": "positive"
          },
          {
            "factor": "known_vulnerabilities",
            "value": false,
            "impact": "positive"
          }
        ]
      },
      "token_distribution": {
        "score": 45,
        "level": "high",
        "details": [
          {
            "factor": "top_10_holders_percentage",
            "value": 92.5,
            "impact": "negative",
            "threshold": 80
          },
          {
            "factor": "holder_count",
            "value": 245,
            "impact": "negative",
            "threshold": 500
          }
        ]
      },
      "market_factors": {
        "score": 62,
        "level": "medium",
        "details": [
          {
            "factor": "liquidity_usd",
            "value": 124500,
            "impact": "neutral",
            "threshold": 100000
          },
          {
            "factor": "price_volatility_30d",
            "value": 28.4,
            "impact": "negative",
            "threshold": 25
          }
        ]
      },
      "social_signals": {
        "score": 70,
        "level": "medium",
        "details": [
          {
            "factor": "twitter_followers",
            "value": 12500,
            "impact": "positive",
            "threshold": 10000
          },
          {
            "factor": "github_activity",
            "value": "low",
            "impact": "negative"
          }
        ]
      }
    },
    "recommendations": [
      "Monitor wallet concentration closely before investing significant amounts",
      "Research team background and development roadmap",
      "Consider smaller position size due to medium risk profile"
    ]
  }
}

Batch Risk Assessment

Retrieve risk assessments for multiple tokens in a single request.

Endpoint: /risk/batch

Method: POST

Request Body:

{
  "addresses": [
    "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "So11111111111111111111111111111111111111112"
  ],
  "include_details": false,
  "chain": "solana"
}

Example Response:

{
  "success": true,
  "data": [
    {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "name": "Example Token",
      "symbol": "EXT",
      "risk_score": 78,
      "risk_level": "medium",
      "updated_at": "2023-06-15T14:22:31Z"
    },
    {
      "address": "So11111111111111111111111111111111111111112",
      "name": "Wrapped SOL",
      "symbol": "wSOL",
      "risk_score": 12,
      "risk_level": "very_low",
      "updated_at": "2023-06-15T12:10:05Z"
    }
  ]
}

Get Wallet Risk Assessment

Assess the risk profile of a specific wallet address.

Endpoint: /risk/wallet/{address}

Method: GET

URL Parameters:

• address (required) - The wallet address to analyze

Query Parameters:

• include_tokens (optional) - Boolean (default: false) - Include risk assessment for tokens owned by the wallet

• chain (optional) - String (default: "solana") - Blockchain to analyze

Example Response:

{
  "success": true,
  "data": {
    "address": "5YNmS1R9nNSCDzb5a7mMJ1dwK9uHeAAF4CQ8B4EEtu3d",
    "risk_score": 35,
    "risk_level": "low",
    "updated_at": "2023-06-15T10:12:44Z",
    "summary": "This wallet shows normal transaction patterns with limited exposure to high-risk assets.",
    "risk_factors": {
      "transaction_patterns": {
        "score": 25,
        "level": "low",
        "details": [
          {
            "factor": "transaction_frequency",
            "value": "normal",
            "impact": "neutral"
          },
          {
            "factor": "known_scam_interactions",
            "value": false,
            "impact": "positive"
          }
        ]
      },
      "asset_composition": {
        "score": 40,
        "level": "low",
        "details": [
          {
            "factor": "high_risk_token_percentage",
            "value": 8.2,
            "impact": "neutral",
            "threshold": 20
          }
        ]
      }
    },
    "owned_tokens": [
      {
        "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
        "name": "Example Token",
        "symbol": "EXT",
        "balance": 1250.75,
        "risk_score": 78,
        "risk_level": "medium"
      }
    ]
  }
}

Get Github Repository Risk Assessment

Assess the risk profile of a GitHub repository associated with a token project.

Endpoint: /risk/github/{owner}/{repo}

Method: GET

URL Parameters:

• owner (required) - GitHub repository owner/organization

• repo (required) - Repository name

Example Request:

curl -X GET "https://api.orama.xyz/v1/risk/github/solana-labs/solana" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "success": true,
  "data": {
    "owner": "solana-labs",
    "repo": "solana",
    "risk_score": 15,
    "risk_level": "very_low",
    "updated_at": "2023-06-14T22:45:12Z",
    "summary": "This repository demonstrates excellent development practices with strong community engagement and regular updates.",
    "risk_factors": {
      "activity": {
        "score": 10,
        "level": "very_low",
        "details": [
          {
            "factor": "commit_frequency",
            "value": "very_high",
            "impact": "positive"
          },
          {
            "factor": "last_update_days",
            "value": 1,
            "impact": "positive",
            "threshold": 30
          }
        ]
      },
      "community": {
        "score": 15,
        "level": "very_low",
        "details": [
          {
            "factor": "stars_count",
            "value": 12500,
            "impact": "positive",
            "threshold": 1000
          },
          {
            "factor": "contributors_count",
            "value": 245,
            "impact": "positive",
            "threshold": 10
          },
          {
            "factor": "fork_count",
            "value": 2800,
            "impact": "positive",
            "threshold": 100
          }
        ]
      },
      "documentation": {
        "score": 20,
        "level": "very_low",
        "details": [
          {
            "factor": "has_readme",
            "value": true,
            "impact": "positive"
          },
          {
            "factor": "documentation_quality",
            "value": "high",
            "impact": "positive"
          }
        ]
      }
    }
  }
}

Get Twitter Account Risk Assessment

Assess the risk profile of a Twitter account associated with a token project.

Endpoint: /risk/twitter/{username}

Method: GET

URL Parameters:

• username (required) - Twitter username

Example Request:

curl -X GET "https://api.orama.xyz/v1/risk/twitter/SolanaStatus" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "success": true,
  "data": {
    "username": "SolanaStatus",
    "risk_score": 25,
    "risk_level": "low",
    "updated_at": "2023-06-14T18:22:05Z",
    "summary": "This account demonstrates consistent and professional communication with a established history.",
    "risk_factors": {
      "account_quality": {
        "score": 20,
        "level": "very_low",
        "details": [
          {
            "factor": "account_age_days",
            "value": 1155,
            "impact": "positive",
            "threshold": 90
          },
          {
            "factor": "has_profile_image",
            "value": true,
            "impact": "positive"
          },
          {
            "factor": "has_verified_badge",
            "value": true,
            "impact": "positive"
          }
        ]
      },
      "engagement": {
        "score": 30,
        "level": "low",
        "details": [
          {
            "factor": "followers_count",
            "value": 268000,
            "impact": "positive",
            "threshold": 1000
          },
          {
            "factor": "following_to_followers_ratio",
            "value": 0.001,
            "impact": "positive",
            "threshold": 2
          }
        ]
      },
      "content_analysis": {
        "score": 25,
        "level": "low",
        "details": [
          {
            "factor": "post_frequency",
            "value": "moderate",
            "impact": "neutral"
          },
          {
            "factor": "suspicious_keywords_frequency",
            "value": "very_low",
            "impact": "positive"
          }
        ]
      }
    },
    "associated_addresses": [
      {
        "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
        "found_in": "bio",
        "date_mentioned": "2023-01-15T10:22:31Z"
      }
    ]
  }
}

Risk Score Calculation

Risk Levels

Risk scores range from 0 to 100 and are classified into risk levels:

Risk Score Range	Risk Level	Description
0-20	Very Low	Minimal risk factors identified
21-40	Low	Few risk factors with limited impact
41-60	Medium	Some concerning factors present
61-80	High	Multiple significant risk factors identified
81-100	Very High	Critical risk factors present, extreme caution advised

Score Components

Risk scores are calculated using a weighted algorithm that considers multiple factors:

Token Risk Factors:

• Contract security and audits (25%)

• Token distribution and ownership concentration (25%)

• Liquidity and trading patterns (20%)

• Team transparency and background (15%)

• Social media presence and community activity (15%)

Wallet Risk Factors:

• Transaction patterns and history (40%)

• Interaction with known scam addresses (30%)

• Asset composition and diversification (30%)

GitHub Risk Factors:

• Repository activity and maintenance (40%)

• Community engagement and adoption (30%)

• Documentation quality and completeness (20%)

• Security practices and vulnerability responses (10%)

Twitter Risk Factors:

• Account quality and authenticity (40%)

• Engagement metrics and follower quality (30%)

• Content analysis and communication patterns (30%)

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key does not have access to the requested resource
404	Not Found - Requested resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Error Response Format

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Token address not found",
    "details": "The specified address does not exist or is not a valid token contract"
  }
}

Webhooks

Orama supports webhooks to notify your application when risk assessments change significantly.

Set Up a Webhook

Endpoint: /webhooks

Method: POST

Request Body:

{
  "url": "https://your-app.com/orama-webhook",
  "events": ["token.risk_change", "wallet.risk_change"],
  "threshold": 10,
  "addresses": [
    "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  ]
}

Parameters:

• url (required) - The URL to send webhook notifications to

• events (required) - Array of event types to subscribe to

• threshold (optional) - Minimum risk score change to trigger notification (default: 5)

• addresses (optional) - Specific addresses to monitor (if empty, monitors all addresses you have previously analyzed)

Example Webhook Payload:

{
  "event": "token.risk_change",
  "timestamp": "2023-06-15T14:22:31Z",
  "data": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "name": "Example Token",
    "symbol": "EXT",
    "previous_risk_score": 45,
    "current_risk_score": 78,
    "change": 33,
    "change_factors": [
      {
        "factor": "ownership_concentration",
        "previous_value": 65,
        "current_value": 92.5,
        "impact": 20
      },
      {
        "factor": "liquidity_change",
        "previous_value": 250000,
        "current_value": 124500,
        "impact": 13
      }
    ]
  }
}

SDKs and Integration

Orama provides official SDKs for popular programming languages:

• JavaScript/TypeScript: npm package
• Python: PyPI package
• Rust: Crates.io package

Example JavaScript integration:

import { OramaClient } from 'orama-api';

const orama = new OramaClient('YOUR_API_KEY');

async function checkTokenRisk(address) {
  try {
    const riskData = await orama.getTokenRiskAssessment(address, { includeDetails: true });
    console.log(`Risk Score: ${riskData.risk_score} (${riskData.risk_level})`);
    
    if (riskData.risk_score > 60) {
      console.warn('High risk token detected!');
      console.warn('Risk factors:', riskData.risk_factors);
    }
    
    return riskData;
  } catch (error) {
    console.error('Error checking token risk:', error);
  }
}

Best Practices

1. Cache Results: Risk scores typically don't change frequently. Consider caching results for up to 24 hours for common tokens.

2. Rate Limit Management: Implement exponential backoff for retry logic when hitting rate limits.

3. Batch Requests: Use batch endpoints when analyzing multiple addresses to reduce API calls.

4. Webhook Usage: For applications monitoring many tokens, use webhooks instead of polling to reduce API load.

5. Security: Store your API key securely and never expose it in client-side code.