Obol Agent Quickstart (5 minutes)

Build and run a minimal “agent” that calls Obol’s POST /v1/execute endpoint, prints the output, and logs an execution receipt you can store for auditing.

• Pricing: $0.005 / call
• No secrets in this repo: use .env locally (placeholder key in .env.example).

What’s in this repo

• agent-node/ — runnable Node.js example that calls /v1/execute and prints the receipt
• web/ — static landing page you can publish via GitHub Pages

---

1) Prerequisites

• Node.js 18+ (Node 20 recommended)
• An Obol API key

---

2) Setup (copy‑paste)

git clone https://github.com/<YOUR_ORG_OR_USER>/obol-agent-quickstart.git
cd obol-agent-quickstart/agent-node
cp .env.example .env
# edit .env and set OBOL_API_KEY
npm install
npm run dev

---

3) POST /v1/execute examples

cURL

curl -sS https://api.obol.app/v1/execute \
  -H "Authorization: Bearer $OBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Write a one-sentence summary of why receipts are useful.",
    "options": {"temperature": 0.2}
  }'

JavaScript (Node 18+)

const res = await fetch("https://api.obol.app/v1/execute", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OBOL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "Say hello from Obol in 5 words.",
    options: { temperature: 0.2 },
  }),
});

const data = await res.json();
console.log(data);
console.log("receipt:", data.receipt ?? res.headers.get("x-obol-receipt"));

Python

import os, requests

r = requests.post(
  "https://api.obol.app/v1/execute",
  headers={
    "Authorization": f"Bearer {os.environ['OBOL_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={"input": "Return JSON: {\"ok\": true}", "options": {"temperature": 0.0}},
)
print(r.json())
print("receipt:", r.headers.get("x-obol-receipt"))

---

4) Receipts & security model

• Don’t ship your API key to browsers. Use server-side calls, functions, or local scripts.
• Receipts are audit artifacts returned alongside responses (either in the body or via headers). Store them to:
  • correlate requests with billing
  • make debugging and post-hoc verification easier
  • prove what was executed and what was returned

Receipt shape can vary; the example prints both data.receipt and x-obol-receipt.

---

5) Publish the landing page (GitHub Pages)

The landing page lives in web/.

1. Push this repo to GitHub
2. GitHub repo → Settings → Pages
3. Source: Deploy from a branch
4. Branch: main and folder: /web

URL: https://<user>.github.io/obol-agent-quickstart/

---

License

MIT