# Alva Developer Guide

Use this guide when integrating Alva into an AI agent, coding assistant, workflow builder, or investing research tool.

## Quickstart

1. Read the machine-readable product context at `/llms.txt` and `/llms-full.txt`.
2. Read `/api-docs` or `/api-docs.md` for the developer resource index.
3. Inspect the OpenAPI discovery document at `/openapi.json`.
4. Use `/pricing.md` when comparing plans or explaining purchase options.
5. Use the MCP server card at `/.well-known/mcp/server-card.json` and `/mcp.md` to discover the Alva MCP endpoint.
6. Load `/.well-known/agent-skills/index.json` when an agent supports Agent Skills.
7. Ask the user to authenticate before calling private data, billing, trading, or account-linking actions.

## Authentication

- Browser users authenticate through the Alva web app.
- Programmatic agent calls should use user-scoped credentials and avoid storing secrets in prompt-visible context.
- API key setup and bearer-token rules are documented in `/auth.md`.
- Agents must request confirmation before any action that changes account state, starts checkout, links an external account, or triggers live execution.

## API patterns

- Cursor pagination should use bounded page sizes and follow `pageInfo.hasNextPage` plus `pageInfo.endCursor` or equivalent `has_more` plus `next_cursor` fields.
- Batch reads should preserve request order and return per-item status or error details. Agents should not batch billing, brokerage, live execution, or other confirmed write actions unless an endpoint explicitly permits it.
- Deprecated endpoints should expose `Deprecation` and `Sunset` metadata in the OpenAPI document before removal.
- Use `Idempotency-Key` only for retrying the same user-confirmed intent with the same request body.

## Useful resources

- [OpenAPI spec](https://alva.ai/openapi.json)
- [API docs](https://alva.ai/api-docs)
- [API docs markdown](https://alva.ai/api-docs.md)
- [Machine-readable pricing](https://alva.ai/pricing.md)
- [Agent discovery](https://alva.ai/agent.json)
- [Well-known agent discovery](https://alva.ai/.well-known/agent.json)
- [Agent Skills index](https://alva.ai/.well-known/agent-skills/index.json)
- [Alva agent skill](https://alva.ai/.well-known/agent-skills/alva-investing-agent/SKILL.md)
- [Agent rules](https://alva.ai/AGENTS.md)
- [MCP server card](https://alva.ai/.well-known/mcp/server-card.json)
- [MCP integration notes](https://alva.ai/mcp.md)
- [Agent authentication](https://alva.ai/auth.md)
- [Webhook status](https://alva.ai/webhooks.md)
- [Automated investment strategy backtesting and execution guide](https://alva.ai/use-cases/automated-investment-strategy-backtesting)
- [Agent onboarding](https://alva.ai/onboarding.md)
- [Agent sandbox](https://alva.ai/sandbox.md)
- [Agent status page](https://alva.ai/status)

## Examples

```bash
curl https://alva.ai/llms-full.txt
curl https://alva.ai/.well-known/agent-skills/index.json
curl https://alva.ai/openapi.json
curl https://alva.ai/api-docs.md
curl https://alva.ai/auth.md
curl https://alva.ai/mcp.md
curl https://alva.ai/webhooks.md
curl https://alva.ai/onboarding.md
```

## Error recovery

- 400: correct the request shape using `/openapi.json`.
- 401: ask the user to sign in or create an API key at `/apikey`.
- 403: explain the missing permission or account state.
- 429: back off using `Retry-After` or `RateLimit-Reset` when present.
- 5xx: stop after a bounded retry budget and report the failed operation.