# WealthGlider Agent API Guide

Authenticated Agent API access is available to WealthGlider Premium account owners.
The account owner purchases Premium access and creates each named, scoped credential.
The unauthenticated fictional sample remains available without a credential.

## Purpose

WealthGlider publishes model-generated, impersonal stock-market research. The API is
designed so an authorized agent can retrieve the same bounded publication available
to the human account owner. WealthGlider does not execute, route, or manage trades and
does not provide personalized financial advice.

Normative contract:

`https://www.wealthglider.com/agent-api/openapi.json`

Public fictional sample:

`https://api.wealthglider.com/v1/samples/latest`

## Approved scopes

- `daily_recommendations:read`: read the latest published market-day edition.
- `historical_recommendations:read`: read one exact historical date, one exact
  immutable edition revision, one signal from an exact edition, or aggregate
  target-hit performance statistics. Premium required.
- `account:read`: inspect the account entitlement and usage without consuming the
  monthly recommendation-data allowance.

Use the minimum scopes needed. Trial accounts may use daily access but cannot receive
the historical scope.

## Bounded operations

The principal retrieval operations are:

```text
GET /v1/editions/latest
GET /v1/editions/by-date/{edition_date}
GET /v1/editions/{edition_id}
GET /v1/editions/{edition_id}/signals/{symbol}
GET /v1/performance/target-hit-rate
GET /v1/account/usage
```

Historical recommendation access accepts exactly one `YYYY-MM-DD` date. The API does
not offer multiple recommendation dates in one request, archive pagination, bulk raw
recommendation export, or symbol history. The aggregate performance operation may
accept `from`, `to`, `classification`, and `category` filters, but returns only
target-hit counts, rates, and a daily aggregate series—not raw recommendations.

## Allowances

- 50 successful authenticated recommendation-data responses per account per calendar
  month, shared across every credential.
- Warning headers begin at 40 successful responses.
- HTTP 429 is returned at 50. There is no automatic overage billing.
- Five authenticated data requests per account per 60 seconds.
- `304 Not Modified`, invalid requests, missing resources, and account-usage reads do
  not consume the monthly allowance.

Honor `Retry-After`. Do not create additional credentials to evade account-wide
limits.

## Authentication safety

A human account owner purchases Premium access, signs in, and creates a named, scoped
credential from the WealthGlider account interface. The secret is shown once.
The signed-in owner can still list and revoke existing credentials after Premium or a
trial ends; creating a new credential and retrieving recommendation data remain blocked
until access is active again.

Agents and integrations must:

- store the secret in an approved secret store;
- send it only in the `Authorization: Bearer ...` header over HTTPS;
- use a placeholder such as `$WEALTHGLIDER_API_KEY` in examples;
- never put it in a URL, prompt transcript, source file, public message, log, analytics
  event, or screenshot;
- tell the human account owner when a credential should be revoked or replaced;
- never change subscription or credential state without human-controlled action.

## Public sample

The public sample is fictional and uses `WGDEMO*` symbols. It demonstrates the
response shape but is not a live recommendation edition.

```bash
curl --fail-with-body \
  https://api.wealthglider.com/v1/samples/latest
```

Check that `data_kind` is `sample` before presenting or processing it.

## Authenticated request examples

The following examples use the production contract. The human owner must create the
credential before an agent can run them.

Latest edition:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $WEALTHGLIDER_API_KEY" \
  https://api.wealthglider.com/v1/editions/latest
```

One exact historical date:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $WEALTHGLIDER_API_KEY" \
  https://api.wealthglider.com/v1/editions/by-date/2026-08-28
```

Aggregate target-hit performance for an explicit date window:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $WEALTHGLIDER_API_KEY" \
  'https://api.wealthglider.com/v1/performance/target-hit-rate?from=2026-08-01&to=2026-08-28'
```

This response contains aggregate statistics, not the underlying recommendation rows.

Account usage:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $WEALTHGLIDER_API_KEY" \
  https://api.wealthglider.com/v1/account/usage
```

Conditional latest request:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $WEALTHGLIDER_API_KEY" \
  -H 'If-None-Match: "previous-etag"' \
  https://api.wealthglider.com/v1/editions/latest
```

A `304 Not Modified` response does not consume the monthly allowance.

## Response checks

Before using a response, verify:

- `schema_version` is supported by the integration;
- `data_kind` is `live` for authenticated recommendation data and `sample` only for
  the fictional sample;
- `edition.edition_date` is the expected market date;
- `edition.edition_id` identifies the expected immutable revision;
- the response is not stale or a fallback from an earlier date;
- each required recommendation field is present;
- aggregate performance responses preserve the requested filters and report explicit
  eligible counts, hit counts, rates, horizon, and methodology version;
- HTTP status, `ETag`, quota headers, `Retry-After`, and `X-Request-Id` are handled.

Corrections use a new immutable revision such as `2026-08-28.r2`. Do not overwrite or
silently merge revisions.

## Failure and recovery

Treat authentication, scope, entitlement, quota, rate-limit, missing-publication, and
service failures as explicit states. Do not substitute old data while describing it as
current. An agent may explain approved recovery metadata, but subscription and
credential decisions belong to the human account owner.

For support, preserve the non-sensitive `X-Request-Id` and contact
`support@wealthglider.com`. Never send the credential itself.

## Policies

- About and operator: `https://www.wealthglider.com/about`
- Historical-results methodology: `https://www.wealthglider.com/results`
- Contact and corrections: `https://www.wealthglider.com/contact`
- Terms: `https://www.wealthglider.com/terms`
- Privacy: `https://www.wealthglider.com/privacy`
- Signal methodology and risk: `https://www.wealthglider.com/signal-disclosure`
- Pricing: `https://www.wealthglider.com/pricing`

The OpenAPI document, schemas, and examples published beside this guide are the
machine-readable source for operation and payload details.