Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt

Use this file to discover all available pages before exploring further.

An Agent Capability Token (agt_…) lets an AI agent shop on a specific customer’s behalf — within boundaries the customer chose. It is the differentiator slice of Stella: every merchant gets agent traffic for free because /api/agent/* is just a different token type on the same backend.

​
What makes an agent token different

AspectStorefront tokenCustomer tokenAgent token
IdentifiesA merchantA logged-in customerAn agent + a customer + a budget
LifetimeIndefinite~24h, renewableBounded by expires_at
Spending limitNone (merchant trust)None (customer’s own card)Hard budget_cents cap
Per-call auditMutations onlyMutations onlyEvery call, every endpoint
Auto-completes paymentn/aIf buyer confirmsNever — always returns a checkout URL the human must tap
Modeled on OAuth’s device flow because LLMs can’t open embedded browsers. The customer never sees the agent’s screen, and the agent never sees the customer’s password. Tokens never travel through the agent’s process before the customer has explicitly approved.

​
What an agent can do

/api/agent/* is a separate API surface optimized for LLM tool-use:
EndpointEffect
GET /agent/catalog/searchLLM-shape product search
POST /agent/intent/findNL query → ranked candidates
POST /agent/intent/find-and-addOne-shot: find + create cart + add
POST /agent/intent/find-and-buyOne-shot: find + cart + checkout. Returns checkout_url for the human to tap. Stella never auto-pays.
GET /agent/customer/meCustomer profile (capability-token-aware)
GET /agent/audit/meAgent’s own action history

​
Budget enforcement

Every mutation that allocates spend (find-and-buy, find-and-add if followed by checkout completion) checks: 
if budget_used_cents + line_total_cents > budget_cents:
    return 402 PAYMENT_REQUIRED { "error": "budget_exceeded" }
budget_used_cents is incremented in the same transaction that finalizes the order (CheckoutFinalizer.consume_budget), so partial failures can’t double-spend.

​
Per-customer agent cap

A customer can have at most 10 active agent tokens at any time. The 11th consent/poll returns: 
HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "error": "agent_cap_exceeded" }
The consent code stays approved — the customer can revoke an existing token and the next poll will succeed without re-issuing.

​
Audit trail

Every agent call writes to audit_events with:
  • actor_type = "agent"
  • actor_id = <agent_token_id>
  • action = <endpoint>
  • payload_hash
  • IP, UA, correlation ID
Customers see their full agent history at: 
GET /api/storefront/customer/me/agents/{token_id}/audit
Merchants see aggregate per-agent activity in the dashboard’s My agents panel.

​
Revocation

Three paths, all instant:
  • Customer revokes from the dashboard’s customer-side My agents panel.
  • Customer revokes via API: DELETE /api/storefront/customer/me/agents/{id}.
  • Merchant revokes from the dashboard’s merchant-side panel (compliance / abuse cases).
The next agent call fails with 401.

​
Try it from the CLI

The reference smoke harness lives at examples/agent-cli/ in the agenticom repo. Seven subcommands cover the full flow: 
agent-cli mint --scopes catalog:read,cart:write --budget 5000 --expires-in 1h
agent-cli poll
agent-cli search "black M tee"
agent-cli buy --product-id ...
agent-cli audit
agent-cli me
agent-cli revoke