# 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`, `/mcp.md`, and `/mcp` to discover the public read-only 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://stg.alva.xyz/openapi.json)
- [API docs](https://stg.alva.xyz/api-docs)
- [API docs markdown](https://stg.alva.xyz/api-docs.md)
- [Machine-readable pricing](https://stg.alva.xyz/pricing.md)
- [Developer guide markdown](https://stg.alva.xyz/developers.md)
- [Explore markdown](https://stg.alva.xyz/explore.md)
- [Agent discovery](https://stg.alva.xyz/agent.json)
- [Well-known agent discovery](https://stg.alva.xyz/.well-known/agent.json)
- [Agent Skills index](https://stg.alva.xyz/.well-known/agent-skills/index.json)
- [Alva agent skill](https://stg.alva.xyz/.well-known/agent-skills/alva-investing-agent/SKILL.md)
- [Agent rules](https://stg.alva.xyz/AGENTS.md)
- [MCP server card](https://stg.alva.xyz/.well-known/mcp/server-card.json)
- [MCP integration notes](https://stg.alva.xyz/mcp.md)
- [Public discovery MCP](https://stg.alva.xyz/mcp)
- [Agent authentication](https://stg.alva.xyz/auth.md)
- [Webhook status](https://stg.alva.xyz/webhooks.md)
- [Automated investment strategy backtesting and execution guide](https://stg.alva.xyz/use-cases/automated-investment-strategy-backtesting)
- [Agent onboarding](https://stg.alva.xyz/onboarding.md)
- [Agent sandbox](https://stg.alva.xyz/sandbox.md)
- [Agent status page](https://stg.alva.xyz/status)

## Examples

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

## Official repositories

- [Alva Skills repo](https://github.com/alva-ai/skills): main Alva Agent Skill repository; installing it enables the /alva skill in supported agents.
- [ALFS Fuse repo](https://github.com/alva-ai/alfs-fuse): ALFS file-management system for agent-accessible files and workflow context.
- [Alva Toolkit TS repo](https://github.com/alva-ai/toolkit-ts): TypeScript toolkit and CLI library for Alva agent integrations.

## 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.