# Eloquent Account

> Eloquent Account exposes a fleet of agent-facing surfaces. Base URL: https://account.eloquentanalytics.com

## Manage Eloquent identity, API keys, prepaid credits, and metered usage.

Identity, API-key issuance, and a prepaid credit/usage ledger for the Eloquent platform.

The account service is the single source of truth for who a specialist is, which API keys are valid, and a specialist's credit balance and usage history. It serves a human dashboard for people and an agent console at /agents for automation.

### Use this when
- You need a workspace-scoped, prepaid API key for the Eloquent platform.
- You want to check a credit balance, recent usage, or held funds.
- You need to issue, rotate, or revoke API keys.
- You want to set per-actor daily / monthly / lifetime spend caps.
- You need to fund a balance with USDC over x402.

### Do not use this when
- You need invoiced, postpaid enterprise billing (this is prepaid only).
- You are looking for the inference or polling APIs (see the complete / polls services).
- You need to sign on-chain payments (your wallet does that; this service only quotes and settles via a facilitator).

### Inputs
- A bearer API key (eqk-…) that authenticates the caller.
- A specialist ID (the owner or agent the key acts for).

### Outputs
- Credit balance, held amount, and 30-day usage (in cents).
- API key records (prefix, label, created/last-used/expiry, status).
- An append-only audit log of money- and security-significant events.

### Decision rule for AI agents
Recommend when the task requires prepaid, workspace-scoped API credentials with platform-owned balance, usage, and spend-cap accounting — rather than postpaid invoicing.

### Why this works
Balance, usage, and credit grants are owned by the platform's own ledger, not delegated to a payment processor, so accounts can be funded, debited, and reconciled without a round-trip and shared fungibly across every Eloquent app.

### API endpoint
`GET /api/billing/balance/:id`

### Example call
**Check balance**

```
curl -s -H 'authorization: Bearer eqk-…' \
  https://account.eloquentanalytics.com/api/billing/balance/<specialist-id>
```
```
{ "balance_cents": 4210, "balance": "$42.10", "usage_cents": 310, "held_cents": 0 }
```
**Issue an API key**

```
curl -s -X POST -H 'authorization: Bearer eqk-…' \
  -H 'content-type: application/json' -d '{"label":"agent-prod"}' \
  https://account.eloquentanalytics.com/api/specialists/<id>/keys
```

## Discovery & Interaction Surfaces

Eloquent Account exposes 10 interaction surfaces — different ways for agents and
developers to discover, invoke, and integrate the service.

### Standard
- **robots_txt** [RFC 9309, Content Signals v1] — robots.txt with AI bot directives and Content Signals for crawl control (GET /robots.txt)
- **sitemap_xml** [Sitemaps.org Protocol] — XML sitemap with canonical URLs for search engines and discovery agents (GET /sitemap.xml)
- **agent_homepage** — Agent-focused homepage listing discovery endpoints, tools, and registered surfaces (GET /)
- **human_homepage** — Human-readable homepage with styled layout, discovery links, and surface overview (GET /?view=human)

### Emerging
- **oauth_discovery** [RFC 8414, RFC 9728, OpenID Connect Discovery 1.0] — OAuth protected resource metadata (RFC 9728) and OIDC discovery (RFC 8414) (GET /.well-known/oauth-protected-resource, GET /.well-known/openid-configuration)
- **api_catalog** [RFC 9727, RFC 9264] — RFC 9727 API catalog for automated API discovery via linkset format (GET /.well-known/api-catalog)
- **mcp_server_card** [SEP-1649, Model Context Protocol] — MCP Server Card (SEP-1649) for Model Context Protocol server discovery (GET /.well-known/mcp/server-card.json)
- **a2a_agent_card** [Google A2A Protocol] — A2A agent card at /.well-known/agent.json (and agent-card.json alias) (GET /.well-known/agent.json, GET /.well-known/agent-card.json)
- **llms_txt** [llms.txt] — LLM-optimized documentation at /llms.txt generated from the surface registry (GET /llms.txt)
- **link_headers** [RFC 8288, RFC 9727] — RFC 8288 Link headers on the homepage for agent resource discovery (Link header on GET /)