APIs & Developer Experience

Degents is designed to feel familiar to both web-service engineers and on-chain builders. Every capability exposed to agents—wallet calls, policy queries, plugin discovery—can also be driven by external apps through well-typed network APIs, a one-command CLI, and dual language SDKs. This section lays out the surfaces you can build on.

8.1 REST & gRPC Gateways

Purpose	Human-readable, cURL-friendly integration	Low-latency, strongly typed micro-services
Auth	OAuth 2.1 (PKCE) or API key (HMAC)	Mutual-TLS + optional JWT
Streaming	Server-Sent Events (/v1/stream/receipts)	Bidirectional streams for intents & receipts
Rate-limits	Token bucket per org, burstable	gRPC interceptors with back-pressure

Endpoint families

POST /v1/intents	Submit an intent drafted outside Degents (e.g., by a mobile app).
GET /v1/agents/{id}	Inspect health, balances, and current coalitions.
GET /v1/actions	Query registry, filter by tag (?tag=NFT).
GET /v1/receipts/{hash}	Fetch canonical transaction receipts plus policy verdict.
POST /v1/policy/simulate	Dry-run an intent and receive a verdict without signing.

OpenAPI JSON is version-pinned (/spec/v1.4.json) and auto-regenerated on every release so client stubs stay up to date.

8.2 CLI & Local Emulator

# install pipx install degents # or: npm i -g degents # scaffold a new strategy agent in Python degents init arbitrage-bot --template=python # run everything locally (Postgres + Ganache fork) cd arbitrage-bot degents dev

• Hot reload – code changes pick up instantly; state persists in a dot-folder.

• Debug UI – localhost:7000 opens a React dashboard with real-time agent logs, gas spend, and policy verdicts.

• Forked chains – --fork=https://mainnet.infura.io spins up a main-net mirror for safe testing.

8.3 SDK Walk-throughs

Python

from degents import Agent, action @action def hello(ctx, name: str): return f"Hello {name}, ETH is {ctx.adapters.price.eth_usd():.0f} USD" agent = Agent("greeter") agent.load_plugin("dex") # instant access to dex.swap, etc. agent.listen() # handle incoming intents

TypeScript (Edge-ready)

import { Agent, dex } from "@degents/ts"; const agent = new Agent("edge-maker"); agent.use(dex()); agent.onIntent("market.update", async (ctx, payload) => { if (payload.gap > 0.01) { await ctx.actions.dex.swap({ sell_token: "USDC", buy_token: "WETH", amount_in: payload.usdcSize, slippage_bps: 30 }); } }); agent.start();

Both SDKs share identical action signatures—switching languages is a copy-paste operation.

8.4 Observability & Debugging

Trace Explorer	Intent → policy → tx path with timings	degents trace <intent-id>
Gas Profiler	Gas used vs quoted, bundle savings	Web dashboard “Gas” tab
Policy Replay	Deterministic re-run of a verdict using stored fork	degents replay --intent ...
Prometheus / Grafana	CPU, mem, intent QPS, wallet nonce lag	Auto-exposed /metrics

Log records conform to OpenTelemetry’s semantic conventions; choose JSONL or OTLP exporters.

8.5 Deployment Recipes

Docker / K8s	docker compose up → helm upgrade --install	Side-car policy verifier, persistent volumes for journal.
Serverless	degents deploy aws-lambda	Cold-starts preload policy & wallet keys from KMS.
Edge (Cloudflare Workers)	degents build --wasm	Ships without journal layer; writes batched to HQ via gRPC.
Desktop (Tauri)	degents pack --desktop	Bundles SQLite and LiteFS; perfect for air-gapped signers.

Deployment manifests embed the build hash and SBOM, ensuring reproducible builds and verifiable provenance.

8.6 First-Five-Minute Checklist

1. Install CLI (pipx or npm -g).

2. Create: degents init treasury-guardian.

3. Configure keys: degents keys import --from-env.

4. Run Devnet: degents dev --fork=mainnet --gas-cap=100.

5. Ship: degents deploy docker — your agent is live, observable, and policy-guarded.

With ergonomic tooling, consistent APIs, and deep debugging aids, developers can go from idea to safely transacting agent in minutes—no glue code, no mystery boxes