API documentation.

Bearer tokens

Send your key in the Authorization header on every request. Shepherd stores only a hash of each key.

Authorization: Bearer shep_live_xxxxxxxxxxxxxxxx

Scopes

Create a key per integration with POST /api-keys, give it the least scope it needs, and set expires_in_days if it is temporary. POST /api-keys/{id}/rotate issues a replacement and keeps the old key working for a grace period (24 hours by default), so you can roll a key without downtime.

Rate limits

Each key gets 600 requests a minute (120 in the sandbox), or the limit you set on it. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit you get 429 with Retry-After. Reports (income statement, balance sheet) run a few at a time; if they are all busy you get 503 with Retry-After.

Safe retries

Add an Idempotency-Key header (any unique string, up to 255 characters) to a POST. Sending the same key and body again within 24 hours returns the first response, with Idempotent-Replayed: true, and does nothing twice. The same key with a different body returns 422. Every response also carries an X-Request-Id to quote when you contact us.

Build before you have a live key

A sandbox is a private, throwaway copy of the API with synthetic data. Every endpoint behaves as it does live, except that nothing touches a chain.

• Instant. POST /sandbox/signup returns a shep_test_ key and seeds a demo customer (cust_demo) with a wallet, 40 classified transactions over about 90 days, and a couple left for review.
• Connect any address. POST /wallets on any address and chain generates realistic activity for it. POST /wallets/{id}/scan adds a few new transactions each time, so polling and webhooks have something to show.
• Same everything else. Classification, entities, statements, opening balances, accruals, rules, reconciliation and webhooks all work as documented.
• Reset any time. POST /sandbox/reset restores the seed data and keeps your key and webhooks. Sandboxes unused for 30 days are deleted. Limit of 10 wallets.

{
  "api_key": "shep_test_...",
  "livemode": false,
  "base_url": "https://app.getshepherd.co/api/v1",
  "seeded": { "end_user_id": "cust_demo", "wallet_id": 1, "address": "0x5a4d...c0de", "chain": "base" }
}

Get a sandbox key

Know when the books change

Register an HTTPS endpoint and Shepherd will POST a signed JSON event when something happens, so you don't have to poll.

Event shape

{
  "id": "evt_55881f55b8e7844ada399eac",
  "type": "wallet.scan_completed",
  "created": 1792380604,
  "livemode": true,
  "data": {
    "wallet_id": 17,
    "address": "0xYourWalletAddress",
    "chain": "base",
    "end_user_id": "cust_4821",
    "transactions_saved": 12,
    "transactions_classified": 10,
    "transactions_needing_review": 2,
    "triggered_by": "api"
  }
}

livemode is false for sandbox events. Use id to deduplicate: delivery is at least once, and order isn't guaranteed.

Register an endpoint

curl -X POST https://app.getshepherd.co/api/v1/webhooks \
  -H "Authorization: Bearer $SHEPHERD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.yourapp.com/shepherd/webhook",
       "events": ["wallet.scan_completed", "transaction.reclassified"]}'
# => { "id": 3, "secret": "whsec_...", ... }   store the secret, it is shown once

hook = shep.webhooks.create(
    "https://api.yourapp.com/shepherd/webhook",
    events=["wallet.scan_completed", "transaction.reclassified"],
)
secret = hook["secret"]   # shown once

const hook = await shep.webhooks.create({
  url: "https://api.yourapp.com/shepherd/webhook",
  events: ["wallet.scan_completed", "transaction.reclassified"],
});
const secret = hook.secret; // shown once

Verify the signature

Every request carries Shepherd-Signature: t=<unix time>,v1=<hex>. The signature is HMAC-SHA256, keyed with your endpoint secret, over the timestamp, a dot, and the raw request body. Verify against the raw bytes, not re-serialized JSON, and reject timestamps more than five minutes old.

from flask import Flask, request
from shepherd import construct_event, SignatureVerificationError

app = Flask(__name__)

@app.post("/shepherd/webhook")
def shepherd_webhook():
    try:
        event = construct_event(request.get_data(), request.headers["Shepherd-Signature"], WEBHOOK_SECRET)
    except SignatureVerificationError:
        return "", 400
    if event["type"] == "wallet.scan_completed":
        refresh_books(event["data"]["end_user_id"])
    return "", 200

import express from "express";
import { constructEvent } from "@getshepherd/sdk";

const app = express();

app.post("/shepherd/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = constructEvent(req.body, req.header("Shepherd-Signature"), process.env.WEBHOOK_SECRET);
    if (event.type === "wallet.scan_completed") refreshBooks(event.data.end_user_id);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});

# The signature is HMAC-SHA256 over "{t}.{raw body}", hex-encoded.
# Header:  Shepherd-Signature: t=1792380604,v1=5257a869e7ec...
import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) <= tolerance
    return fresh and hmac.compare_digest(expected, parts["v1"])

Delivery and retries

• Respond with any 2xx within 10 seconds. Anything else, or a timeout, is retried.
• Up to 7 attempts: immediately, then after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours. After that the delivery is marked failed.
• Redirects aren't followed. URLs must be https and publicly reachable. For local development, use a tunnel.
• GET /webhooks/{id}/deliveries shows recent attempts with status codes and errors.

Official Python and Node clients

Typed, with automatic retries on reads, error classes for each status, createSandbox(), and webhook verification built in. Node is zero-dependency. For any other language, generate a client from the OpenAPI spec.

# pip install shepherd-sdk   (Python 3.8+)
from shepherd import Shepherd

shep = Shepherd("shep_live_...")

wallet = shep.wallets.connect("0x...", "base", end_user_id="cust_4821")
pnl = shep.statements.income(start_date="2026-09-01", end_user_id="cust_4821")

for hook in shep.webhooks.list():
    print(hook["url"], hook["events"])

// npm install @getshepherd/sdk   (Node 18+, zero dependencies, ships types)
import { Shepherd } from "@getshepherd/sdk";

const shep = new Shepherd(process.env.SHEPHERD_API_KEY);

const wallet = await shep.wallets.connect({ address: "0x...", chain: "base", end_user_id: "cust_4821" });
const pnl = await shep.statements.income({ start_date: "2026-09-01", end_user_id: "cust_4821" });

for (const hook of await shep.webhooks.list()) console.log(hook.url, hook.events);

Serving multiple customers

Platforms usually need to keep each customer's books apart. There are two building blocks, and they combine.

• End users. Tag wallets with your own end_user_id. The wallets, transactions list, and income statement can be filtered to one end user. Lightweight, and a good fit when you mostly need per-customer views.
• Entities. Create an entity per customer for separate sets of books, then read each one, or a consolidated view across all of them, from the statement endpoints.

Most platforms use both: an end user tag for lightweight per-customer views, and an entity where a customer needs its own books.

Workspaces: one set of books per customer

If you embed Shepherd for your own customers, give each one a workspace. A workspace is a fully separate organization: its own accounts, transactions, chart of accounts, rules, statements and period locks. Nothing is shared between workspaces.

1. POST /workspaces with your id for the customer. It is safe to repeat: the same external_id returns the same workspace.
2. Send your normal requests with the header Shepherd-Workspace: <external_id>. Every endpoint then reads and writes that customer's books only.
3. Without the header you are in your own organization. A workspace can only be reached with a key from the platform account that created it.

Workspaces are on for every API account (sandbox keys can try them, up to 10). POST /workspaces/{id}/delete permanently removes a workspace and its data; it requires confirm set to the external_id.

Push your own transactions

If you already hold the customer's money movements, such as a bank ledger or custodial stablecoin accounts, send them to Shepherd instead of connecting a wallet. Shepherd books and classifies them the same way.

1. Create an account with POST /accounts: your external_id, a type of bank, credit_card, stablecoin or ledger, and a currency.
2. Push transactions with POST /accounts/{id}/transactions, up to 1000 per call. Each item needs your external_id, a date and an amount; add direction, counterparty and category where you have them. The response says how many were created, how many already existed, and lists any rejected items with the reason.
3. Resend freely. external_id is the key: the same transaction twice is stored once, and a corrected amount or date updates it (unless that date falls in a closed period, in which case the stored row is left as it was and flagged for review).
4. Classification runs in the background. The response includes a job_id; poll GET /jobs/{id}, or subscribe to the transactions.classified webhook.

Foreign currency amounts are converted to the books' functional currency at the rate on the transaction date. A transaction in a currency with no available rate is stored and held out of the statements until one exists, and counted in the statements' unpriced total.

Pagination and syncing

GET /transactions, /audit-log and /workspaces return a page plus has_more and next_cursor. Pass next_cursor back as cursor until has_more is false. limit is 1 to 1000.

To keep a copy of the books in your own database, call GET /transactions?updated_since=<timestamp>. Results come oldest change first, so you can store the timestamp of the last row you processed and ask again from there. Subscribe to webhooks to know when to ask.

Endpoints

Every path below is relative to https://app.getshepherd.co/api/v1. Mutations use POST, including deletes. Long lists are paginated (see Pagination and syncing); other lists are short and unpaginated.

Wallets

Accounts

Jobs

Transactions

Financial statements

Entities

Opening balances

Accruals

Classification rules

Reconciliation

Chart of accounts

Periods

Audit log

API keys

Workspaces

Webhooks

Sandbox

Status codes

Errors return a non-2xx status and a JSON body with code (stable, safe to branch on), message (for people), request_id, and error (the same text as message, kept for older clients). Malformed JSON returns 400 invalid_json.

{
  "error": "chain must be one of: base, ethereum, polygon, arbitrum, tempo, solana",
  "code": "invalid_request",
  "message": "chain must be one of: base, ethereum, polygon, arbitrum, tempo, solana",
  "request_id": "req_9c1f0a7e4b2d6a83c5e1"
}

Spec, SDKs and tools