Data API reference

Quick start

1. Create an account at /developers/signup, then a key at /developer. Test keys (ds_test_…) are free and need no credits.
2. Send it as a Bearer token. Every response is { data, meta }.
3. Check meta.creditsCharged and meta.creditsBalance as you go.

curl "https://depositscout.com/api/developer/v1/rates?type=easy-access&provider=chase" \
  -H "Authorization: Bearer $DS_API_KEY"

Authentication

Base URL https://depositscout.com/api/developer/v1. Send Authorization: Bearer ds_live_… on every request. Keys are never accepted in the query string or in X-API-Key. A key is shown once when created; revoke it from the portal if it leaks. Live keys can carry an IP allow-list.

Credits & pricing

Requests are prepaid in DS Credits: £1 = 10 DS Credits. New accounts start with 20 free credits. Top up from £5 (presets £5, £20, £50, £100). Credits never expire. Each request costs the endpoint's weight below — a page of results is one request. 304 Not Modified, validation errors, 429 and 5xx are free.

Responses are shared between callers for up to 60 seconds, so a busy endpoint stays fast; each request is still charged. Cancellation and refunds: see the refund policy.

Counting catches up a moment later. Usage is written a few seconds behind the calls it counts, so a request you made a second ago may not be in /me, the usage page or your balance yet. Nothing is lost — it settles within a few seconds. /me returns usage.asOf so you can tell what the figures are true as of, rather than assuming they are live. Charging itself is immediate: the credits for a request are taken as it is served, and meta.creditsBalance on that response is already up to date.

Pagination & caching

• Lists take ?limit= (default 25, maximum 50 — larger values are clamped and the applied value is in meta.limit) and ?cursor= from meta.nextCursor.
• ?fields=a,b,c trims each item to the fields you need.
• Every response carries an ETag. Send it back as If-None-Match and an unchanged result is a free 304 — this is how pollers keep costs down.
• Dates are ISO 8601 UTC; money is a two-decimal GBP string; rates are strings like "4.42".

Rate limits

60 requests per minute per live key (10 for test keys) and 5,000 per day per account across all keys. Over either limit you get 429 with Retry-After. Every response includes X-RateLimit-Limit, -Remaining and -Reset.

Webhooks

Coming soon — this section describes how webhooks will work so you can plan for them.

Instead of polling, we can call your endpoint when something changes. Webhooks are switched on per account — ask from the Webhooks page of your dashboard.

• Events: rate.changed, product.added, product.withdrawn, switch_offer.changed. Filter each endpoint by provider, account type or minimum rate change so you only pay for what you use.
• Payload: { id, type, createdAt, attempt, data }, where data is the same shape the matching endpoint returns (a history row, a product, an offer).
• Signature: every request carries X-DS-Signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 of `${t}.${rawBody}` with your endpoint's secret. Reject anything older than five minutes. Also sent: X-DS-Event and X-DS-Delivery.
• Retries: a non-2xx response or a timeout (10s) is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then marked dead; you can redeliver from the dashboard.
• Pricing: 5 DS Credits per deliveredevent (first 2xx only — retries are never charged again). Test events are free. If your balance can't cover the next delivery the endpoint pauses, not deletes, and resumes when you top up.

import { createHmac, timingSafeEqual } from "node:crypto";

// Verify before trusting the body. Use the raw request body, not a re-serialised object.
export function verifyDepositScoutSignature(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1, "hex"));
}

Endpoints

Errors

Every error is JSON with error, a plain-English message that says what to do next, requestId and a docs link. None of them cost credits.

Versioning

/v1 shapes are frozen: we only add fields. A breaking change ships as /v2 with a six-month overlap and Deprecation / Sunset headers, announced on the changelog. Use of the API is under the Data Licence v2026-09.