SDK Examples

curl -X GET "https://api.shoal.xyz/v1/entities/byName?name=ethereum&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

import os, requests
API_KEY = os.environ.get("SHOAL_API_KEY", "YOUR_API_KEY")
r = requests.get(
    "https://api.shoal.xyz/v1/entities/byName",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"name": "ethereum", "limit": 5},
)
print(r.json())

const API_KEY = process.env.SHOAL_API_KEY || 'YOUR_API_KEY';
const url = new URL('https://api.shoal.xyz/v1/entities/byName');
url.searchParams.set('name', 'ethereum');
url.searchParams.set('limit', '5');
const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
console.log(await res.json());

curl -X GET "https://api.shoal.xyz/v1/timeline/byOrganizationId?id=23151&since=2026-02-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

requests.get(
  "https://api.shoal.xyz/v1/timeline/byOrganizationId",
  headers={"Authorization": f"Bearer {API_KEY}"},
  params={"id": 23151, "since": "2026-02-01T00:00:00Z", "limit": 10}
)

const radarRes = await fetch(
  'https://api.shoal.xyz/v1/timeline/byOrganizationId?id=23151&since=2026-02-01T00:00:00Z&limit=10',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

curl -X GET "https://api.shoal.xyz/v1/entities/23151/relationships?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

requests.get(
  "https://api.shoal.xyz/v1/entities/23151/relationships",
  headers={"Authorization": f"Bearer {API_KEY}"},
  params={"limit": 10}
)

const res2 = await fetch(
  'https://api.shoal.xyz/v1/entities/23151/relationships?limit=10',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

curl -X GET "https://api.shoal.xyz/v1/signal/byCategory?category=partnership" \
  -H "Authorization: Bearer YOUR_API_KEY"

requests.get(
  "https://api.shoal.xyz/v1/signal/byCategory",
  headers={"Authorization": f"Bearer {API_KEY}"},
  params={"category": "partnership"}
)

const res3 = await fetch(
  'https://api.shoal.xyz/v1/signal/byCategory?category=partnership',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

import time

cursor = "2026-02-01T00:00:00Z"

while True:
    r = requests.get(
        "https://api.shoal.xyz/v1/signal/all",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={"since": cursor},
    )
    data = r.json()["data"]
    if data:
        cursor = data[0]["latestPostTimestamp"]
        for event in data:
            print(event["title"], event["signal"])
    time.sleep(60)

curl -X GET "https://api.shoal.xyz/v1/brief/batch?ids=526,765,1024&since=2026-02-28T00:00:00Z&compact=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

PORTFOLIO = "526,765,1024,2048"

r = requests.get(
    "https://api.shoal.xyz/v1/brief/batch",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"ids": PORTFOLIO, "since": "2026-02-28T00:00:00Z", "compact": "true"},
)

data = r.json()
for org in data["organizations"]:
    if org["counts"]["signal"] > 0:
        print(f"{org['label']}: {org['counts']['signal']} new signals")

const portfolio = '526,765,1024,2048';
const briefRes = await fetch(
  `https://api.shoal.xyz/v1/brief/batch?ids=${portfolio}&since=2026-02-28T00:00:00Z&compact=true`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { organizations } = await briefRes.json();
organizations
  .filter(org => org.counts.signal > 0)
  .forEach(org => console.log(`${org.label}: ${org.counts.signal} new signals`));

curl -X GET "https://api.shoal.xyz/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"