BUILD ON IT / ELPIS

Your first verified job

Create a real committed job, preview a decision, record the result and replay its attestation. No deposit required.

What you'll build

A job requiring delivery of an exact file, checked against a SHA-256 digest agreed in advance.

You'll create a job in your own organization. This records evidence decisions; it does not fund escrow or transfer tokens.

Prefer to explore first? Open the playground without an account.

1. Get a scoped key

Create an account.
Open Developer workspace and create a key with read and propose.
Copy the secret once and store it outside your source code or chat prompts.

Terminal

export ELPIS_API_KEY="paste-your-issued-key-here"
export ELPIS_URL="https://elpis.devilabs.dev"

Never grant an unattended agent the approve scope. Possession of a key with that scope provides privileged API authority.

2. Commit the acceptance condition

This example uses an actual SHA-256 digest of the UTF-8 text Elpis sample report v1. Calculate it locally:

Terminal

printf 'Elpis sample report v1' | shasum -a 256
# bfb0c59be7146dc7bcac41c0edfdf49ef65caee08498e9076ee42b99ac3b26bf

POST /api/v1/jobs

curl -fsS -X POST "$ELPIS_URL/api/v1/jobs" \
  -H "Authorization: Bearer $ELPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-report-v1" \
  -d '{
    "provider": "sample-agent",
    "description": "Deliver the agreed example report",
    "condition": [{"kind":"deliverable_hash","hash":"0xbfb0c59be7146dc7bcac41c0edfdf49ef65caee08498e9076ee42b99ac3b26bf"}]
  }'

The response is wrapped in a data object. Copy data.id to your environment as JOB_ID. The stored commitmentHash identifies the terms.

Use a new idempotency key for new terms. Reusing the same key with different details returns a conflict.

3. Preview the evidence

The read-scoped verification endpoint evaluates the proof without finalizing the job.

POST /api/v1/jobs/{id}/verify

export JOB_ID="paste-data.id-here"
curl -fsS -X POST "$ELPIS_URL/api/v1/jobs/$JOB_ID/verify" \
  -H "Authorization: Bearer $ELPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proof":{"deliverableHash":"0xbfb0c59be7146dc7bcac41c0edfdf49ef65caee08498e9076ee42b99ac3b26bf"}}'

Look at data.decision, data.checks and data.reasons. An exact match can produce release; a contradiction can produce refund; insufficient evidence normally produces hold while pending.

4. Record the decision

When you're ready to commit the evidence result, call the settlement-decision endpoint. This is **not** an on-chain payment.

POST /api/v1/jobs/{id}/settle

curl -fsS -X POST "$ELPIS_URL/api/v1/jobs/$JOB_ID/settle" \
  -H "Authorization: Bearer $ELPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-decision-v1" \
  -d '{"proof":{"deliverableHash":"0xbfb0c59be7146dc7bcac41c0edfdf49ef65caee08498e9076ee42b99ac3b26bf"}}'

Decision	Meaning
`release`	Acceptance rule satisfied by presented evidence. Any payment requires independent execution.
`refund`	Condition rejected or deadline policy returned a refund verdict. No automatic chain refund is implied.
`hold`	Required information or authority is missing. Nothing should release on this verdict.

5. Replay the record

A stored decision can be recomputed from its canonicalized inputs. Replay detects whether the current inputs produce the recorded attestation—not whether the real-world work was good.

POST /api/v1/attestations/{id}/replay

curl -fsS -X POST "$ELPIS_URL/api/v1/attestations/$JOB_ID/replay" \
  -H "Authorization: Bearer $ELPIS_API_KEY"

The authenticated console also provides a Jobs list and a replay page for each decided job.

Where to go next

For real agent integrations, see SDKs and MCP. To understand authenticated witnesses, read Verification. For treasury execution, start at Run your treasury and Security.