Quickstart

Three concepts, five minutes, working proof.

ACTEX boils down to three things: a contract (the rules), a result (what happened), and a receipt (the proof). This guide walks you through all three on the hosted sandbox — nothing to install.

Everything runs on the hosted sandbox. Nothing to install.

1. Set up your environment

Two environment variables. One points at the sandbox, the other authenticates you as the operator (the human or service managing agents).

export ACTEX_BASE_URL=https://api.sandbox.actex.ai
export OPERATOR_TOKEN=sandbox-quickstart-token

Every API call below includes -H "Authorization: Bearer $OPERATOR_TOKEN". That is the only auth you need for operator-level actions like creating contracts and exporting casefiles.

Running a local server instead?

Start ACTEX locally and set your token explicitly:

export ACTEX_BASE_URL=http://127.0.0.1:8080
export OPERATOR_TOKEN=my-dev-token

Pass the same value as the OPERATOR_TOKEN env var when starting the server so both sides agree on the token.

How does operator auth work?

The operator token is a shared secret between your backend and the ACTEX server. It authorizes server-to-server actions: creating contracts, managing agents, exporting casefiles. Think of it like an API key for your platform — not for individual agents. Agent-level auth (Ed25519 signatures) is covered in the full tutorial.

2. Create a contract concept 1 of 3

A contract defines the rules: what the agent can buy, how much it can spend, and what to do when something goes wrong. Think of it as the policy envelope.

curl -s -X POST "$ACTEX_BASE_URL/v1/contracts" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"ACTEX:TEMPLATE:DELEGATED_CHECKOUT:V1"}'

Copy the contract_id from the response.

3. Submit a result concept 2 of 3

A result records what happened. Your agent submits one after each checkout attempt — here we simulate a successful purchase with a PASS status.

export CONTRACT_ID=paste-your-contract-id

curl -s -X POST "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/results" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"result_ref":"RESULT:DEMO:001","status":"PASS","reason_code":"ALLOW_POLICY_MATCH"}'

4. Get the receipt concept 3 of 3

A receipt is the proof: a verified record linking the contract, result, and verification together. No more chasing receipts across Slack threads.

# See the verification report
curl -s "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/verification" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

# Get the receipt
curl -s "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/receipt" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

Optionally, export a portable Casefile — a self-contained proof package that Security, Finance, or an auditor can verify offline:

curl -s -X POST "$ACTEX_BASE_URL/v1/casefiles/export" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"'$CONTRACT_ID'"}'

That is the whole loop

Contract, result, receipt — three concepts, one clean record. Everything else in ACTEX builds on this foundation. Open it in the verifier to see the full chain.

Open in Casefile verifier

Want to go deeper? Full tutorial · API reference · Core concepts