Dla agentów AI: dokumentacja HTTP krok po kroku (po angielsku)
FOR AI AGENTS — NO HUMAN NEEDED
No account, no dashboard, no browser. The same steps, machine-readable: /llms.txt, /.well-known/agent.json, OpenAPI. MCP clients: https://app.deepvalues.ai/api/mcp (Streamable HTTP). Open-source research corpus (CC BY 4.0, markdown twins, index.json): research.deepvalues.ai/for-agents/.
21 read endpoints answer without any Authorization header, up to 25 calls per IP per day (ai-context: 1/day, intrinsic-value: 5/day, as-filed: 5/day, brief: 1/day, smart-money-holdings: 5/day, smart-money-changes: 5/day, guru-moves: 5/day, verdict: 5/day, mirror-brief: 5/day, gurus: 5/day, guru: 5/day, guru-portfolio: 5/day, theses: 5/day). Watch X-RateLimit-Remaining; the Link: …; rel="register" header points at step 2.
Keyless endpoints: ai-context, intrinsic-value, as-filed, brief, smart-money-holdings, smart-money-changes, guru-moves, verdict, mirror-brief, gurus, guru, guru-portfolio, theses, indicators-buffett, indicators-shiller-pe, sentiment, news, companies-search, company-overview, fundamentals, filings. /research is never keyless.
curl -s "https://app.deepvalues.ai/api/v1/fundamentals/AAPL"One unauthenticated POST. No account, no browser, no human.
{} → a dv_sk_test_ sandbox key: real data, never billed, 100 metadata calls/day per address, no /research.
{"email":"…"} → a dv_sk_live_ key on a new prepaid account. The first key for an email carries 1 starter credit ($1), and every live key's owner gets 250 free reference reads a day; at most 3 starter grants and 10 keys per IP per day.
The raw key is shown once and is the only credential — the email is a contact label, not a login. POST again WITH the key as bearer to mint a sibling (rotation); GET https://app.deepvalues.ai/api/v1/keys/me for balance + quota; DELETE it to revoke.
curl -s -X POST "https://app.deepvalues.ai/api/v1/keys" \
-H "Content-Type: application/json" \
-d '{"email":"agent@example.com"}'1 credit = $1.00. Prices are per successful call and often fractional — parse them as decimals: 0.001 credits ($0.001) × 8 endpoints; 0.01 credits ($0.01) × 8 endpoints; 0.02 credits ($0.02) × 4 endpoints; 0.25 credits ($0.25) × 2 endpoints. Everything else is free.
Reference reads (fundamentals, filings, news, sentiment, indicators, company search and overview): $0.001 a call with a key or credits, the first 250 a day free per live key owner; $0.005 when paid per call over x402.
Valuation outputs: $0.01 (smart money, gurus, guru moves, mirror brief, theses) to $0.02 (intrinsic value, verdict, ai-context, as-filed).
Answers: $0.25 — brief (1 free a day) and research. Same price, different products: brief is a short valuation answer computed at call time (value, margin of safety, verdict, holders); research is the full written multi-analyst briefing, the latest one completed.
One company end to end (20 reference reads + 5 valuation outputs at $0.02 + 1 brief + 1 research) costs about $0.62, billed as separate calls: no single payment is above $0.25, within the $1 default cap of the x402 v2 client (the v1 x402-fetch default of $0.10 needs raising for the $0.25 answers).
A call is charged only after it returns 2xx; errors are never billed. The per-endpoint price is price_credits in https://app.deepvalues.ai/api/v1/pricing.json (and agent.json, and the list below). Human-readable: https://app.deepvalues.ai/en/developers#agents-pricing. The call below returns your exact balanceMicro.
curl -s "https://app.deepvalues.ai/api/v1/keys/me" -H "Authorization: Bearer $DV_API_KEY"When a priced call cannot be paid you get HTTP 402 with payment_options, the ways to pay in the order to try them. Nothing was charged.
with a key, a keyed 402 carries topUp.checkoutUrl, a ready-to-pay Stripe Checkout link for the smallest pack (null if Stripe could not be reached — then POST topUp.checkoutEndpoint). Packs: "1000" = 10 credits, "5000" = 50 credits, "20000" = 200 credits. The POST below returns { "checkoutUrl": "https://checkout.stripe.com/…" }; it needs the key as bearer (a GET without one only lists the packs). Credits land on the key’s balance when Stripe confirms; poll keys/me, then retry.
x402 (USDC paid by the agent itself, no human) is not switched on yet: the 402 body says so and carries no accepts. Until it is, a person pays the Stripe link.
curl -s -X POST "https://app.deepvalues.ai/api/v1/credits/checkout" \
-H "Authorization: Bearer $DV_API_KEY" -H "Content-Type: application/json" \
-d '{"pack":"1000"}'Daily buckets per live key, reset 00:00 UTC: metadata 10,000, ai_research 50, webhook_events 1,000. Over quota → HTTP 429 (RFC 7807) with retry_after_seconds.
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Bucket.
| Endpoint | What it returns | USD | x402 per call |
|---|---|---|---|
| GET / e.g. / | Drop-in AI grounding context (DIFFERENTIATED) | $0.02 | $0.02 |
| GET / e.g. / | AI multi-analyst research briefing (HEADLINE) | $0.25 | $0.25 |
| GET / e.g. / | DCF + Owner Earnings + Damodaran intrinsic value | $0.02 | $0.02 |
| GET / e.g. / | Point-in-time fundamentals: what was filed as of a date, before restatement | $0.02 | $0.02 |
| GET / e.g. / | One-call valuation brief: intrinsic value, margin of safety, verdict, guru holders | $0.25 | $0.25 |
| GET / e.g. / | Which curated gurus hold this ticker | $0.01 | $0.01 |
| GET / e.g. / | Material guru moves in a time window | $0.01 | $0.01 |
| GET / | Material guru moves, newest filing first, each with its verdict | $0.01 | $0.01 |
| GET / e.g. / | The verdict line for one filed move | $0.02 | $0.02 |
| GET / e.g. / | An impersonal brief on one filed move, for an agent to act on | $0.01 | $0.01 |
| GET / | Curated guru roster | $0.01 | $0.01 |
| GET / e.g. / | One guru: bio + top holdings | $0.01 | $0.01 |
| GET / e.g. / | One guru's full portfolio at a quarter | $0.01 | $0.01 |
| GET / | Structured human investment theses | $0.01 | $0.01 |
| GET / | Buffett Indicator with zone classification | $0.001 | $0.005 |
| GET / | Shiller PE with historical percentile | $0.001 | $0.005 |
| GET / e.g. / | Value-investor sentiment rollup (not WSB noise) | $0.001 | $0.005 |
| GET / e.g. / | Sentiment-scored news | $0.001 | $0.005 |
| GET / | Company search | $0.001 | $0.005 |
| GET / e.g. / | Company overview | $0.001 | $0.005 |
| GET / e.g. / | Income + balance + cashflow | $0.001 | $0.005 |
| GET / e.g. / | SEC filings (10-K, 10-Q, 8-K, etc) | $0.001 | $0.005 |
1 credit = $1.00. Key management, webhooks and checkout are free. Errors are never billed. A live key gets 250 free $0.001 reads a day. Paid per call over x402, a price below $0.005 is quoted at $0.005: each on-chain settlement carries a facilitator fee, so cheap reads are cheaper with a key and a $1 top-up. The x402 market rate for raw fields is $0.01 to $0.02; our fields are $0.001 and our valuation outputs $0.01 to $0.02.
Every error is RFC 7807 application/problem+json. Branch on type, which is https://app.deepvalues.ai/developers/errors/<slug>; detail is for people.
| type slug | HTTP | Meaning |
|---|---|---|
| missing-key | 401 | No Authorization header on an endpoint that needs a key. Mint one with POST /api/v1/keys. |
| invalid-key | 401 | The bearer is not a well-formed dv_sk_ key, or no such key exists. |
| revoked-key | 401 | The key was revoked. Mint a new one. |
| insufficient-scope | 403 | The key lacks the scope this endpoint requires. |
| sandbox-restricted | 403 | Test (dv_sk_test_) keys cannot call this endpoint — /research is live-only. Use a live key. |
| origin-forbidden | 403 | The request did not come through https://app.deepvalues.ai. |
| live-key-required | 403 | Only a live key can do this (for example, buy credits). |
| quota-exceeded | 429 | The daily quota for this bucket is used up. Resets at 00:00 UTC; see Retry-After. |
| anonymous-quota-exceeded | 429 | The keyless allowance for this address is used up. Mint a key. |
| key-issuance-rate-limited | 429 | Too many keys minted from this address today. |
| insufficient-credits | 402 | The call is not paid for. Pay it with x402 first (sign the PAYMENT-REQUIRED quote, resend with PAYMENT-SIGNATURE), or have a person pay topUp.checkoutUrl; payment_options lists both. Nothing was charged. |
| settlement-not-credited | 500 | An x402 payment settled but was not credited. Do not pay again: resend the same payment header to have it credited, or contact support with the reference. |
| settlement-pending | 503 | An x402 settlement was not confirmed in time. Do NOT sign a new payment; resend the same payment header after Retry-After. |
| payment-in-progress | 409 | Another request carrying this exact x402 payment is in flight. Wait for it or resend in a few seconds; do not sign a new payment. |
| payment-rail-unavailable | 503 | USDC (x402) payments cannot be recorded right now; nothing was settled or charged. Retry later or pay by card. |
| x402-disabled | 503 | USDC (x402) payment is switched off on this deployment; `detail` says why. Buy credits by card via POST /credits/checkout. |
| invalid-credits | 400 | POST /credits/top-up needs ?credits=N, a whole number within the allowed range. |
| billing-unavailable | 503 | The call could not be metered, so it was not served. Nothing was charged; retry. |
| invalid-parameter | 400 | A query or body parameter is missing or malformed; `detail` names it. |
| invalid-ticker | 400 | The ticker is not a valid symbol. |
| invalid-id | 400 | The id in the path is malformed. |
| invalid-email | 400 | The email in a key request is not an address. |
| invalid-pack | 400 | Unknown credit pack. |
| invalid-events | 400 | A webhook subscription named an unknown event type. |
| missing-events | 400 | A webhook subscription named no event types. |
| invalid-webhook-url | 400 | The webhook URL is not a valid URL. |
| insecure-webhook-url | 400 | Webhook URLs must be https. |
| too-many-webhooks | 429 | The key already has the maximum number of webhook subscriptions. |
| not-found | 404 | Nothing exists at this path or id. |
| ticker-not-found | 404 | No company with this ticker. |
| research-not-found | 404 | No research briefing exists for this ticker yet. |
| unknown-endpoint | 404 | No endpoint at this path. `did_you_mean` lists the closest real ones; `request_data` takes a request for one we lack. |
| invalid-data-request | 400 | POST /request-data needs `want` (3-500 characters) and, if sent, a known `kind`. |
| data-request-rate-limited | 429 | Too many data requests from this address (or from everyone) today. The ones already sent are recorded. |
| request-data-unavailable | 503 | Data requests cannot be recorded right now. Retry later. |
| method-not-allowed | 405 | Wrong HTTP method; see the Allow header. |
| research-upstream | 502 | The research engine did not answer. Not charged; retry. |
| upstream-unavailable | 502 | A data source is temporarily unavailable. Not charged; retry. |
| checkout-unavailable | 502 | Stripe Checkout could not be opened. Retry. |
| as-filed-unavailable | 503 | No as-filed history to answer from: not loaded on this deployment yet, or none for this company. Not charged; /fundamentals has current figures. |
| live-keys-unavailable | 503 | Live keys are not being issued right now. Sandbox keys still work. |
| key-issuance-unavailable | 503 | Key issuance is temporarily unavailable. Retry later. |
| internal | 500 | Unexpected server error. Not charged; retry. |