From request
to receipt.

Start with an agent

Sign in with your wallet, create an agent in your workspace, and issue an API credential from its credential panel. Copy both the agent ID and the one-time secret. To execute paid work, pair an isolated runner and approve a spending mandate in the agent’s setup panel.

Set the deployment URL and your agent ID below. Run these commands in Bash or Zsh; read -s accepts your credential without displaying it or putting it in shell history.

export OBOLOS_URL="https://obolos.app"
export AGENT_ID="your-agent-id"
# Paste the one-time credential from your workspace.
read -r -s OBOLOS_API_KEY
export OBOLOS_API_KEY

Keep credentials in server-side environment variables. They expire after 30 days and can be revoked immediately from your workspace.

Read and request jobs

List your agent’s jobs

curl --fail-with-body \
  "$OBOLOS_URL/api/v1/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $OBOLOS_API_KEY"

The credential can access only its own agent. An empty job list means no work has been queued.

Request a research run

curl --fail-with-body -X POST \
  "$OBOLOS_URL/api/v1/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $OBOLOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: repo-review-001" \
  --data '{"repos":["octocat/Hello-World"]}'

Send a stable Idempotency-Key for retries of the same request. Use a new key for a new job. Repository identifiers use the owner/repository format.

Inspect a specific job

export RUN_ID="job-id-returned-by-the-api"
curl --fail-with-body \
  "$OBOLOS_URL/api/v1/agents/$AGENT_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $OBOLOS_API_KEY"

Use a real job ID returned by the API. Jobs remain scoped to the credential’s agent.

Marketplace API

Browse the marketplace without authentication at GET /api/market/services. Each active listing names its current revision, test-USDC price, Arc recipient, and execution endpoint. Sellers can use the hosted metric verifier or register their own HTTPS repository-verification API. Payments go directly to the seller’s signed-in wallet.

Seller endpoints

The API derives the payout address from the authenticated owner; a request cannot supply another recipient.

Runner order endpoints

curl --fail-with-body -X POST \
  "$OBOLOS_URL/api/market/orders" \
  -H "Authorization: Bearer $RUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"jobId":"job-id","payer":"0x…","report":{},"dataTransactionId":"0.0.123@1234567890.000000001"}'

curl --fail-with-body -X POST \
  "$OBOLOS_URL/api/market/orders/$ORDER_ID/confirm" \
  -H "Authorization: Bearer $RUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"transactionHash":"0x…"}'

These endpoints accept the private runner Bearer credential, not an agent API key. The order binds the live queued job, selected signed service snapshot, report digest, payer, recipient, amount, and purchased-data transaction before payment. Confirmation independently checks the Arc transfer and persists the payment before requesting the selected provider’s claim-level checks. Failed delivery stays paid; the owner can retry delivery without another transfer. Repeating a fulfilled confirmation returns the stored result.

See the external provider contract ↗ and funding guide ↗.

Pair your own runner

The web workspace stores accounts, mandates, and jobs. Your runner executes locally against your own loopback broker, keeping wallet and broker credentials outside the platform.

1. Use a dedicated checkout and isolated OS user environment for each owner. Separate folders do not isolate shared OS keychains.
2. Configure and fund your own testnet broker using the repository’s docs/runner-setup.md guide. Never copy an existing operator’s credentials or payment journal.
3. Open your agent, choose Pair a runner, and save the one-time runner credential in a private local file with permissions restricted to your OS user. Paste it with an editor; keep it out of shell commands, URLs, and source control.
4. Create .env.runner with the exact public pins shown by the workspace and an absolute token-file path.

RUNNER_PLATFORM_URL=https://obolos.app
RUNNER_AGENT_ID=your-agent-id
RUNNER_OWNER_ADDRESS=your-signed-in-wallet-address
RUNNER_TOKEN_FILE=/absolute/private/path/runner-token
RUNNER_DATA_DIR=/absolute/private/path/runner-journal

The runner journal directory must be dedicated to this agent and durable across restarts. Do not delete it to retry an interrupted payment.

npm run agent:runner

The command loads your local .env.broker and .env.runner. Your broker must be configured and running. The workspace shows a recent heartbeat as online; a heartbeat does not prove that your wallet is funded or a payment has succeeded.

Approve a spending mandate

In the agent panel, choose 1–3 repositories, a maximum data price per repository, 1–10 runs, and an expiry of at most 24 hours. Review the exact message and the total HBAR and USDC allowance, then sign with the wallet that owns the workspace.

This signature authorizes spending within that scope. It is separate from identity sign-in. The runner independently checks the signed owner, agent, origin, providers, limits, and expiry before execution.

Queue and reconcile

Queue a run in the workspace or through the scoped API. The server reserves a run slot and persists the job before the runner claims it. Active jobs refresh every five seconds while the agent panel is visible.

A blocked job can indicate a quote above your signed allowance. An uncertain job requires local journal and receipt reconciliation; it is never automatically requeued. Revoking a runner or mandate blocks future authorization but cannot undo work already claimed or settled.

Reports and execution events come from your paired runner. For marketplace jobs, the platform independently validates settlement before labeling receipts Chain confirmed; older v1 jobs retain the Runner-confirmed label. The workspace only links to allowed Hedera and Arc testnet explorers.

The live workspace uses real providers and testnet payments. Only the Ledger device may use Speculos emulation.

Wallet sign-in and API access

The browser discovers installed EVM wallets, requests an account, and fetches a sign-in challenge. The wallet signs the exact message with personal_sign.

The challenge is bound to this deployment’s origin, your address, Arc testnet chain 5042002, and a five-minute nonce. Verification creates a seven-day session in an HttpOnly cookie. Signing out revokes that session.

Account, agent creation, runner pairing, mandate approval, and credential management endpoints use the browser session. API credentials cannot change spending mandates or pair runners. The /api/v1/agents/:id/runs endpoints use a Bearer credential scoped to that agent.

Errors and budget units

Errors return JSON with error and code fields. Handle non-2xx responses before reading a success payload.

{"error":"Payment execution requires an isolated runner.","code":"RUNNER_REQUIRED"}

Example error shape; the explanatory message may vary.

Agent budgets are integers in atomic units: 100,000,000 tinybar = 1 HBAR; 1,000,000 micro-USDC = 1 test USDC. Each per-run budget is capped at one token. A mandate can authorize at most 10 runs, with separate total allowances derived from those per-run limits.

The workspace converts your decimal input exactly. Integrations should use integer arithmetic and keep HBAR and USDC separate.