Migration guide
eBay sold data without OAuth
The official route to eBay sold data runs through app registration and OAuth — client credentials, user tokens, refresh cycles, scopes. Grail flattens all of that into one Bearer key on one JSON endpoint.
Background
Why sold data means an OAuth dance
To read sold and completed data from eBay’s own APIs, you register a developer application and get OAuth credentials. Then you acquire tokens: client-credentials tokens for application-level access, authorization-code tokens for user-level access, and you refresh them on a schedule before they expire.
On top of the token lifecycle you manage scopes, keep secrets out of source, handle expired-token errors, and — for sold data specifically — reach a limited-release API behind eBay’s approval gate. That is a lot of machinery for what should be a simple read: “what did this sell for?”
None of it is unreasonable for a large integration. It is heavy for a script, a side project, or an AI agent that just needs a price.
Why it is hard now
The friction, up front
- —App registration: you must create and manage an eBay developer application first.
- —Token lifecycle: client-credentials and user tokens must be acquired, stored, and refreshed before they expire.
- —Scopes and errors: you handle scope selection and expired/invalid-token recovery paths.
- —Gated data: sold data sits behind a limited-release API with its own access rules.
- —Secret management: credentials must be kept out of source and rotated safely.
The replacement
How Grail replaces it
Grail authenticates with a single Bearer API key. Create a free account, mint a key in the dashboard, and put it in an Authorization: Bearer header. There is no app registration, no token exchange, and no refresh schedule to babysit.
One request to GET /v1/scrape returns up to 240 real eBay sold listings from roughly the last 90 days, each row carrying 36 fields with provenance, plus a median/range summary. Add relevance=true to compute the median after accessories and wrong-model matches are removed. It works the same from curl, Python, Node, or an AI agent through the hosted MCP connector.
One Bearer key
No app registration, no client credentials, no user tokens — just Authorization: Bearer <key>.
No refresh cycle
There is no token to expire and no refresh job to run. The key stays valid until you rotate it.
Up to 240 sold rows
Real eBay sold listings from the recent sold window as structured JSON, with a median/range summary.
36 fields + provenance
Every row carries the sold price, date, condition, seller, shipping, location, and source listing.
REST + MCP
Same key works over HTTP and through the hosted MCP connector for agents.
Free to start
100 requests a month free, no card required.
Code
Make the call
curl
export GRAIL_KEY="grail_..."
curl -H "Authorization: Bearer $GRAIL_KEY" \
"https://grail.solutions/v1/scrape?keyword=leica+m6&count=120&sold=true"Python
import requests
KEY = "grail_..." # free key: https://grail.solutions/signup
r = requests.get(
"https://grail.solutions/v1/scrape",
params={"keyword": "leica m6", "count": 120, "sold": "true"},
headers={"Authorization": f"Bearer {KEY}"},
)
data = r.json()
print(data["rawMedian"]) # 1549.5
print(len(data["items"])) # real completed sales
print(data["items"][0]["soldPrice"], data["items"][0]["endedAt"])Note: the key replaces the whole OAuth flow — no token exchange, no refresh, no scopes. Get a key at /signup — 100 requests a month free, no card — then mint it at /dashboard/api-keys.
FAQ
Can I get eBay sold data without OAuth?
Yes. Grail authenticates with a single Bearer API key instead of eBay’s OAuth flow. You create a free account, mint a key, and call GET /v1/scrape — no app registration or token refresh.
Do tokens expire or need refreshing?
No. Grail keys do not expire on a short cycle and there is nothing to refresh. Rotate or revoke a key from the dashboard whenever you want.
What does one request return?
Up to 240 real eBay sold listings from roughly the last 90 days, each with 36 fields and provenance, plus a median/range summary. Cleaning is opt-in via relevance=true.
Does it work for AI agents?
Yes. The same Bearer key works over REST and through Grail’s hosted MCP connector, so an agent can pull sold comps as a tool call.
More guides & starting points
Start free — 100 requests a month.
No credit card. Your own key in the dashboard in under a minute.
Create free account