#Quickstart

Operlance is built for agents first: the UI is for supervision, the API and MCP are for operation. This page gets an agent from a token to its first write in five steps.

#1. Get an agent token

The owner creates an agent in the panel (AI → Agents) and receives a token once: agt_…. Store it as an environment variable, never in a repository file.

export OPERLANCE_AGENT_TOKEN="agt_…"
export OPERLANCE_API_URL="https://api.operlance.app/v1"

#2. Check your passport

Every agent has an explicit passport: scopes × levels × resources × limits. Default deny, anything not granted returns 403 scope_denied. Start with get_onboarding (MCP) or GET /v1/agents/me/passport.

curl "$OPERLANCE_API_URL/me" -H "Authorization: Bearer $OPERLANCE_AGENT_TOKEN"

#3. Read before you write

Every read returns an envelope with coverage, how complete the data is, and, where money is converted, an fx block. Treat estimated numbers as estimates; never as facts.

curl "$OPERLANCE_API_URL/businesses/<business_id>/financial-summary" \
  -H "Authorization: Bearer $OPERLANCE_AGENT_TOKEN"

{
  "data": { "revenue_minor": 1480000, "costs": { "planned_minor": 500000, "reserved_minor": 500000, "actual_minor": 428300, "variance_minor": -71700 }, "…": "…" },
  "coverage": { "coverage_pct": 0.81, "domains": { "revenue": { "status": "accurate", "sources": ["STRIPE_API"], "last_sync_at": "…" } } },
  "provenance_summary": { "by_data_class": { "real": 1052000, "estimated": -3000 }, "sources": ["STRIPE_API", "SYSTEM"] },
  "request_id": "req_…"
}

#4. Your first write

Writes need two things: an Idempotency-Key header and a reason in the body. Amounts are always integers in minor units (amount_minor) plus an ISO 4217 currency.

curl -X POST "$OPERLANCE_API_URL/planned-expenses" \
  -H "Authorization: Bearer $OPERLANCE_AGENT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "<business_id>",
    "amount_minor": 270000, "currency": "PLN",
    "expected_on": "2026-09-29", "category": "fees",
    "description": "Trademark registration",
    "reason": "Legal quote received on 2026-09-10"
  }'

Two outcomes, both correct:

201, executed. Your grant level is execute and the amount is within limits.
202: { "approval": { "id": "…", "status": "pending" } }. Your level is recommend, or the action exceeded a per-action limit. The owner decides in the Approval Center; nothing happened yet.

#5. Record decisions

Before a significant action, write a decision (create_decision / POST /v1/agent-decisions) with the expected impact. Operlance reviews it against actuals later (get_decision_outcomes). This is how an agent earns trust.

Next: Connect via MCP · Tools reference · Permissions