← Back to EchoPrime
📗

Cloud API Documentation

Full reference for the EchoPrime hosted API. Generate, verify, and look up safe primes via HTTP.

Base URL

https://echoprime.xyz/echoprime/api/v1

All endpoints are relative to this base URL. HTTPS only. CORS enabled for browser access.

Authentication

Pass your API key via the x-api-key header:

curl -H "x-api-key: ep_your_key_here" \
  https://echoprime.xyz/echoprime/api/v1/find/100

Free tier: No API key required. Rate limited to 100 requests/day.

Paid tiers: API key required. Get yours from the pricing page.

Rate Limits

Free
$0
100 requests/day
No API key needed
Starter
$99/mo
10,000 requests/day
Priority support
Pro
$499/mo
Unlimited requests
Dedicated support
SLA guarantee

Rate limit headers included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Response Format

All responses follow this structure:

// Success
{
  "success": true,
  "data": { ... },
  "meta": {
    "compute_ms": 4,
    "cached": false
  }
}

// Error
{
  "success": false,
  "error": "Description of what went wrong"
}

Endpoints

GET /api/v1/estimate/:n

Estimate the n-th safe prime using the analytic formula p₍ₙ₎ ≈ 2.8913 · n · (ln n)². Fast, no primality testing — just the estimate.

ParamTypeDescription
nintegerPrime index (≥ 1)
Request
curl https://echoprime.xyz/echoprime/api/v1/estimate/100
Response
{
  "success": true,
  "data": { "index": 100, "estimate": "6139" },
  "meta": { "compute_ms": 0, "cached": false }
}
GET /api/v1/find/:n

Find the actual verified safe prime at index n. Searches from the estimate, caches the result for instant future lookups. This is the primary endpoint.

ParamTypeDescription
nintegerPrime index (≥ 1)
Request
curl https://echoprime.xyz/echoprime/api/v1/find/100
Response (first call — computed)
{
  "success": true,
  "data": {
    "index": 100,
    "p": "6599",
    "q": "3299",
    "index_approx": 100,
    "attempts": 24,
    "verified": true
  },
  "meta": { "compute_ms": 6, "cached": false }
}
Response (subsequent calls — cached)
{
  "success": true,
  "data": {
    "index": 100,
    "p": "6599",
    "q": "3299",
    "score_p": 1,
    "score_q": 1,
    "verified": true
  },
  "meta": { "compute_ms": 1, "cached": true }
}
GET /api/v1/verify/:p

Verify whether a given number is a safe prime. Returns collapse scores and primality results.

ParamTypeDescription
pinteger (string)Number to verify (supports arbitrarily large numbers)
Request
curl https://echoprime.xyz/echoprime/api/v1/verify/23
Response
{
  "success": true,
  "data": {
    "p": "23",
    "q": "11",
    "is_safe_prime": true,
    "score_p": 1.0,
    "score_q": 1.0,
    "verified": true
  },
  "meta": { "compute_ms": 12, "cached": false }
}
POST /api/v1/batch-verify

Verify multiple candidates in a single request. Maximum 100 per batch.

BodyTypeDescription
candidatesarray[int]Array of numbers to verify (max 100)
Request
curl -X POST https://echoprime.xyz/echoprime/api/v1/batch-verify \
  -H "Content-Type: application/json" \
  -d '{"candidates": [23, 47, 59, 83, 100]}'
Response
{
  "success": true,
  "data": {
    "count": 5,
    "results": [
      { "p": "23", "is_safe_prime": true, "verified": true, ... },
      { "p": "47", "is_safe_prime": true, "verified": true, ... },
      { "p": "59", "is_safe_prime": true, "verified": true, ... },
      { "p": "83", "is_safe_prime": true, "verified": true, ... },
      { "p": "100", "is_safe_prime": false, "verified": false, ... }
    ]
  },
  "meta": { "compute_ms": 45, "cached": false }
}
GET /api/v1/lookup/:index

Look up a pre-computed prime by index. Only returns results that have been previously computed and cached. Returns 404 if the index hasn't been computed yet.

ParamTypeDescription
indexintegerPrime index (≥ 1)
Request
curl https://echoprime.xyz/echoprime/api/v1/lookup/100
Response
{
  "success": true,
  "data": {
    "index": 100,
    "p": "6599",
    "q": "3299",
    "score_p": 1,
    "score_q": 1,
    "verified": true
  },
  "meta": { "compute_ms": 0, "cached": true }
}
GET /api/v1/random

Return a random verified safe prime from the database. Useful for testing or when you don't care about the specific index.

Request
curl https://echoprime.xyz/echoprime/api/v1/random
Response
{
  "success": true,
  "data": {
    "index": 42,
    "p": "2459",
    "q": "1229",
    "score_p": 1,
    "score_q": 1,
    "verified": true
  },
  "meta": { "compute_ms": 0, "cached": true }
}
GET /api/v1/stats

Public API statistics. Number of cached primes, total API calls, uptime.

Request
curl https://echoprime.xyz/echoprime/api/v1/stats

Error Codes

200 Success
400 Bad request — invalid parameter (e.g. n must be positive integer)
401 Unauthorized — invalid or missing API key (paid endpoints)
404 Not found — no pre-computed prime at that index (use /find instead of /lookup)
429 Rate limited — too many requests. Upgrade your plan or wait.
500 Internal server error — computation failed

Code Examples

Python (requests)

import requests

BASE = "https://echoprime.xyz/echoprime/api/v1"
HEADERS = {"x-api-key": "ep_your_key_here"}  # optional

# Find a safe prime
r = requests.get(f"{BASE}/find/100", headers=HEADERS)
data = r.json()["data"]
print(f"p = {data['p']}, q = {data['q']}, verified = {data['verified']}")

# Verify a candidate
r = requests.get(f"{BASE}/verify/6599", headers=HEADERS)
print(r.json())

# Batch verify
r = requests.post(f"{BASE}/batch-verify",
    json={"candidates": [23, 47, 100, 6599]},
    headers=HEADERS)
for result in r.json()["data"]["results"]:
    print(f"{result['p']}: {'✅' if result['verified'] else '❌'}")

JavaScript (fetch)

const BASE = 'https://echoprime.xyz/echoprime/api/v1';

// Find a safe prime
const res = await fetch(`${BASE}/find/100`);
const { data } = await res.json();
console.log(`p = ${data.p}, q = ${data.q}`);

// Verify a candidate
const verify = await fetch(`${BASE}/verify/6599`);
console.log(await verify.json());

// Batch verify
const batch = await fetch(`${BASE}/batch-verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ candidates: [23, 47, 100] })
});
console.log(await batch.json());

Node.js (axios)

const axios = require('axios');
const BASE = 'https://echoprime.xyz/echoprime/api/v1';
const headers = { 'x-api-key': 'ep_your_key_here' };

// Find
const { data } = await axios.get(`${BASE}/find/100`, { headers });
console.log(data.data.p); // "6599"

// Random prime
const random = await axios.get(`${BASE}/random`, { headers });
console.log(random.data.data);

SDKs & Libraries

Links