# Agent Code Execution API

Pay per run — execute code in a sandboxed environment via x402 micropayments.

**Endpoint:** `POST /api/agent/execute`
**Price:** `$0.10` per execution
**Network:** Base (eip155:8453) by default

---

## Quick Start (x402-proxy)

The easiest way to call this API is via [`x402-proxy`](https://github.com/cascade-protocol/x402-proxy) — a `curl`-like CLI that automatically handles x402 payment. No wallet setup, no crypto code.

```bash
npx x402-proxy -X POST \
  -H "Content-Type: application/json" \
  -d '{"code":"console.log(41+1);","language":"javascript"}' \
  https://box.codejar.net/api/agent/execute
```

That's it. On first run `x402-proxy` generates a wallet automatically. Fund it with USDC on Base and go.

**Pipe-safe for agent workflows:**

```bash
npx x402-proxy -X POST \
  -H "Content-Type: application/json" \
  -d '{"code":"console.log(41+1);","language":"javascript"}' \
  https://box.codejar.net/api/agent/execute | jq '.stdout'
```

**Force a specific network:**

```bash
npx x402-proxy --network base \
  -X POST -H "Content-Type: application/json" \
  -d '{"code":"console.log(41+1);","language":"javascript"}' \
  https://box.codejar.net/api/agent/execute
```

---

## Request

```json
{
  "code": "console.log('hello')",
  "language": "javascript"
}
```

| Field      | Type     | Required | Description                                |
|------------|----------|----------|--------------------------------------------|
| `code`     | `string` | yes      | Source code to execute                     |
| `language` | `string` | yes      | One of the [supported languages](#supported-languages) |

### Supported Languages

| Language     | `language` value  |
|--------------|-------------------|
| JavaScript   | `javascript`      |
| Python       | `python`          |
| Rust         | `rust`            |
| Go           | `go`              |
| C++          | `cpp`             |
| Java         | `java`            |

---

## Responses

### Success (200)

```json
{
  "success": true,
  "stdout": "hello\n",
  "stderr": "",
  "exitCode": 0
}
```

### Execution Error (200)

Non-zero exit codes are still a 200 response — check `success` and `exitCode`:

```json
{
  "success": false,
  "stdout": "",
  "stderr": "Error: something went wrong\n",
  "exitCode": 1
}
```

### Client Error (4xx)

```json
{
  "success": false,
  "error": "Missing required fields: code, language"
}
```

```json
{
  "success": false,
  "error": "Unsupported language \"ruby\". Supported: javascript, python, rust, go, cpp, java"
}
```

### Server Error (500)

```json
{
  "success": false,
  "error": "Execution engine not configured"
}
```

---

## x402 Payment

This API uses the [x402 protocol](https://x402.org) (HTTP 402 Payment Required) for per-run micropayments.

### The Flow

```
Agent                          Server
  │                               │
  ├── POST /api/agent/execute ──► │
  │                               ├── No payment → 402
  │◄──────────────────────────────┤
  │   402 Payment Required        │
  │   Payment-Required: <encoded> │
  │                               │
  ├── (sign with wallet)          │
  │                               │
  ├── POST /api/agent/execute ──► │
  │   Payment-Signature: <sig>    │
  │                               ├── Verify → Settle → Execute
  │◄──────────────────────────────┤
  │   200 { stdout, stderr, ... } │
```

### Using `x402-proxy` (recommended)

[`x402-proxy`](https://github.com/cascade-protocol/x402-proxy) is a CLI tool that works like `curl` for x402-paid APIs. It auto-detects 402 responses, pays them, and streams the result — zero crypto code needed.

```bash
npx x402-proxy -X POST \
  -H "Content-Type: application/json" \
  -d '{"code":"console.log(41+1);","language":"javascript"}' \
  https://box.codejar.net/api/agent/execute
```

**First-time setup:** The proxy auto-generates a wallet at `~/.config/x402-proxy/wallet.json`. No env vars, no private key management. Just fund the generated address with USDC on Base and run.

**Options:**

| Flag                     | Description                              |
|--------------------------|------------------------------------------|
| `--network base`         | Use Base network (default)               |
| `--verbose`              | Debug the 402 negotiation flow           |
| `--protocol x402`        | Use x402 protocol (default)              |

### Using `x402-proxy` MCP mode (for AI agents)

AI agents can consume this API as an MCP tool with zero config:

```bash
npx x402-proxy mcp add execute \
  https://box.codejar.net/api/agent/execute
```

This auto-detects your AI client (Claude Code, Cursor, VS Code, etc.) and registers the endpoint as a callable MCP tool named `execute`. The agent calls it like any other tool, and `x402-proxy` handles payment transparently.

### Using raw HTTP (for custom code)

If you need to integrate payment logic directly into your code, see the [x402 SDKs](https://github.com/x402-foundation/x402) for client libraries in TypeScript, Python, Rust, and Go.

---

## Configuration (Server Admins)

| Variable                   | Description                              | Default           |
|----------------------------|------------------------------------------|-------------------|
| `X402_NETWORK`             | Blockchain network for payment           | `eip155:8453`     |
| `X402_FACILITATOR_URL`     | x402 facilitator endpoint                | required          |
| `X402_PAY_TO_ADDRESS`      | Wallet address that receives payments    | required          |
| `NEXT_PUBLIC_X402_NETWORK` | Same as X402_NETWORK (exposed to client) | `eip155:8453`     |
| `DAYTONA_API_KEY`          | Daytona sandbox API key                  | required          |

---

## CORS

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Payment-Signature, X-Payment
```

---

## Cost

| Item                | Cost    |
|---------------------|---------|
| Per execution       | $0.10   |
| Network             | Base    |
| Token               | USDC    |
| Payment protocol    | x402 v2 |