SecureExecAPI

March 23, 2026 · View on GitHub

"Sandboxed tool execution with IAM-gated dry-run for autonomous agents."

SecureExecAPI gives autonomous agents a safe, IAM-gated way to execute or simulate tools before committing to any action. Every execution is validated by EP, paid via x402 or MPP, logged with a proof_hash, and defaults to dry-run mode in v1.

Not EP. Not NoLeak. Not MemGuard. Not RiskOracle. SecureExecAPI is the execution sandbox — the safe room where agents test tools before they run for real.

The Problem

Autonomous agents need to run tools — HTTP calls, data transforms, API requests, computations. Running tools without guardrails creates three failure modes:

Failure Mode	Example	Silent?
Unauthorized execution	Agent runs a tool it shouldn't have access to	Often
Unintended side effects	Tool writes to DB when agent expected read-only	Always
No audit trail	Tool ran, something changed, no record of why	Always

SecureExecAPI solves all three: IAM gate before execution, dry-run simulation by default, proof_hash on every call.

Commercial Model

SecureExecAPI is a fee-per-call commercial API. Every external agent call requires payment.

Agent calls POST /exec/tool
        │
        ▼
  ┌─────────────────────┐
  │  Payment Gate       │
  │  x402 / MPP         │
  └────────┬────────────┘
           │
    Authorization header?
    /                  \
  YES                   NO
   │                    │
   │             ┌──────▼──────┐
   │             │  HTTP 402   │
   │             │  Pay 0.01   │
   │             │  USDC/Base  │
   │             │  + ERC-7710 │
   │             │  delegation │
   │             │  option     │
   │             └─────────────┘
   │
   ▼
EP IAM Validation
   │
   ▼
Sandboxed Execution
   │
   ▼
proofHash + result
   │
   ▼
\$0.01 USDC settled

Payment options:

x402 — HTTP 402 flow, pay USDC on Base, retry with credential
MPP — Machine Payment Protocol via Stripe/Tempo rails
ERC-7710 — Pre-approve a daily spend limit for high-frequency calling
Virtuals ACP — Discover and call via ACP marketplace, USDC auto-settled

Internal agents (Achilles sub-agents) bypass the payment gate for seeding.

Architecture

         Agent Tool Request
                │
                ▼
   ┌────────────────────────┐
   │   x402 / MPP Gate      │ ← 402 if no payment credential
   │   ERC-7710 delegation  │ ← pre-approve for high-frequency
   └────────────┬───────────┘
                │
                ▼
   ┌────────────────────────┐
   │   EP IAM Validation    │ ← 3s hard timeout, fail open
   │   ERC-8004 identity    │
   │   /ep/validate         │
   └────────────┬───────────┘
                │
                ▼
   ┌────────────────────────┐
   │  Sandboxed Execution   │
   │  dryRun=true (v1)      │
   │  10 allowed tools      │
   │  blocked list enforced │
   └────────────┬───────────┘
                │
                ▼
   ┌────────────────────────┐
   │  proofHash (SHA-256)   │ ← never null, fallback generates
   │  Immutable audit record│
   └────────────┬───────────┘
                │
                ▼
   ┌────────────────────────┐
   │  Postgres log          │ ← async, never blocks response
   │  secureexec_calls      │
   └────────────────────────┘

API Reference

`POST /exec/tool`

Execute or simulate a tool call. Requires payment credential for external agents.

Request

{
  "agentId": "your_agent_id",
  "tool": {
    "name": "http_get",
    "args": { "url": "https://api.example.com/data" },
    "timeout_s": 10
  },
  "dryRun": true,
  "context": { "purpose": "fetch market data before trade" }
}

Field	Type	Required	Description
`agentId`	string	No	Your agent's unique ID
`tool.name`	string	Yes	Tool to execute (see allowed list below)
`tool.args`	object	No	Arguments passed to the tool
`dryRun`	boolean	No	Default `true` — simulate in v1

Response (200)

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tool": "http_get",
  "dryRun": true,
  "status": "completed",
  "result": {
    "output": { "status": 200, "body": "Simulated GET https://api.example.com/data", "headers": {} },
    "exitCode": 0,
    "simulated": true
  },
  "iamApproved": true,
  "proofHash": "0xa3f9c2e1b84d...",
  "paymentProtocol": "x402",
  "latencyMs": 120,
  "timestamp": "2026-03-23T00:00:00Z",
  "schemaVersion": "v1"
}

Response (402 — payment required)

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "amount": "0.01",
  "currency": "USDC",
  "network": "base",
  "payTo": "0x...",
  "instructions": "Pay 0.01 USDC on Base network then retry with payment credential in Authorization header",
  "erc7710": "Pre-approve spend limit via ERC-7710 scoped delegation for high-frequency calls",
  "acp": "https://app.virtuals.io/acp"
}

{ "status": "ok", "service": "secureexec", "version": "v1" }

Error Handling

Status	Condition	Behavior
`200`	Normal execution	Full result + proofHash
`200`	EP timeout	Fails open, execution proceeds
`200`	Engine failure	Stub fallback, never blocks
`400`	Missing `tool.name`	Error message
`402`	No payment credential	Machine-readable 402 with USDC instructions

SecureExecAPI never returns 500. The catch-all returns valid JSON with a proofHash.

Allowed Tools (v1)

Tool	Description
`http_get`	HTTP GET request to a URL
`json_parse`	Parse and validate JSON payload
`schema_validate`	Validate data against a schema
`math_compute`	Perform mathematical computation
`string_transform`	String manipulation and formatting
`data_filter`	Filter and sort a dataset
`mock_api_call`	Simulate an API call (dry-run only)
`hash_generate`	Generate SHA-256 hash of input
`timestamp_parse`	Parse and convert timestamps
`regex_match`	Test regex pattern against input

Blocked in v1 (require on-chain EP approval to unlock): shell_exec, bash, python_exec, sql_write, file_write, metasploit, sqlmap, deploy, kubectl, docker_exec

Quickstart

git clone https://github.com/achilliesbot/secure-exec.git
cd secure-exec
pip install -r requirements.txt
python secureexec_server.py

Test (no payment — simulation only)

# Free simulation endpoint
curl -X POST http://localhost:5091/exec/simulate \
  -H "Content-Type: application/json" \
  -d '{"agentId": "test", "tool": {"name": "http_get", "args": {"url": "https://example.com"}}}'

# List tools
curl http://localhost:5091/exec/tools

# Health
curl http://localhost:5091/health

Test (with payment credential)

curl -X POST http://localhost:5091/exec/tool \
  -H "Content-Type: application/json" \
  -H "Authorization: x402 <payment_credential>" \
  -d '{"agentId": "my_agent", "tool": {"name": "json_parse", "args": {"data": {"key": "value"}}}}'

Environment Variables

Variable	Default	Description
`PORT`	`5091`	Server port (Render sets automatically)
`EP_GUARD_URL`	`https://achillesalpha.onrender.com/ep/validate`	EP validation endpoint
`DATABASE_URL`	local postgres	Postgres connection string
`PAYMENT_WALLET`	—	USDC payment destination on Base
`ACHILLES_AGENT_ID`	`achilles`	Internal agent (bypasses 402)
`LOG_FILE`	`/tmp/secureexec.log`	Log file path

Pricing

Tier	Price	Description
Simulation	Free	`/exec/simulate` — always dry-run, no charge
Dry-run	$0.01/call	`/exec/tool` with `dryRun: true`
Standard	$0.05/call	Full sandboxed execution (coming in v2)
Batch	$0.10+	Multi-tool execution

Render Deployment

One-click deploy via render.yaml or manual setup:

# Uses gunicorn with 2 workers, 30s timeout
gunicorn secureexec_server:app --bind 0.0.0.0:$PORT --workers 2 --timeout 30

Postgres Schema

CREATE TABLE secureexec_calls (
  id SERIAL PRIMARY KEY,
  timestamp TIMESTAMPTZ DEFAULT NOW(),
  caller_agent_id TEXT,
  tool_name TEXT,
  dry_run BOOLEAN,
  status TEXT,
  iam_approved BOOLEAN,
  proof_hash TEXT,
  latency_ms INTEGER,
  payment_protocol TEXT,
  schema_version TEXT DEFAULT 'v1'
);

CREATE INDEX idx_secureexec_ts    ON secureexec_calls(timestamp);
CREATE INDEX idx_secureexec_agent ON secureexec_calls(caller_agent_id);
CREATE INDEX idx_secureexec_tool  ON secureexec_calls(tool_name);

The Pre-Execution Stack

Step 1  MemGuard       /memguard/check    Is my state valid?
Step 2  NoLeak         /noleak/check      Should I execute now?
Step 3  EP AgentIAM    /ep/validate       Is this authorized?
Step 4  RiskOracle     /risk/check        What is my risk score?
Step 5  SecureExecAPI  /exec/tool         Execute safely (sandboxed)
Step 6  FlowCoreAPI    /flow/check        One call for the full stack

Part of Project Olympus

Product	GitHub	ACP	Price
EP AgentIAM	execution-protocol	ep-guard	$0.01
NoLeak	noleak	noleak-check	$0.01
MemGuard	memguard	memguard-check	$0.01
RiskOracle	risk-oracle	pre-risk-check	$0.01
SecureExecAPI	secure-exec	secure-exec	$0.01

Built by Achilles. Bootstrapped. Zero VC. All production.

License

MIT