# Giga API

Pay-per-run AI agent execution API. Submit a prompt and optional files; an agent runs in an isolated sandbox with full code execution capabilities and produces downloadable output. No API keys — pay per run in USDC on Base via x402.

## Complete Workflow

### 1. Start a run (paid via x402)

```
POST /api/start
```

The endpoint uses x402 payment. Send your prompt; the SDK handles payment automatically. Returns a `runId` immediately — the agent begins executing asynchronously.

### 2. Check status (SIWX auth, free)

```
POST /api/read   body: { "runId": "...", "includeFiles": false }
```

Call `/api/read` every ~5 seconds until `status` is `completed` or `failed`.

### 3. Download output files (SIWX auth + token, free)

```
POST /api/read        body: { "runId": "...", "includeFiles": true }   → get file paths
POST /api/file-url    body: { "runId": "...", "path": "..." }           → get presigned URL
GET  /api/file        ?token=<signed-token>                             → download file (no auth)
```

---

## Endpoints

### POST /api/start (paid)

Start an agent run with a prompt and optional file attachments.

**Input:**
```json
{
  "prompt": "Write a Python script that sorts a CSV by date column",
  "tier": "$0.50",
  "files": [
    {
      "filename": "data.csv",
      "contentType": "text/csv",
      "data": "<base64-encoded file content>"
    }
  ]
}
```

`tier` and `files` are optional. `tier` defaults to `$0.50`. File `data` must be base64-encoded. Filenames are sanitized server-side.

**Payment tiers** (set via the x402 `tier` field):

| Tier key | Price  |
|----------|--------|
| `$0.50`  | $0.50  |
| `$1.00`  | $1.00  |
| `$2.00`  | $2.00  |

Default tier is `$0.50`. x402-compatible clients pass the tier key in the payment `tier` field when fulfilling the 402 response. If your client auto-selects the default, it will pay `$0.50`.

**Output:**
```json
{
  "runId": "clx8m2k4p0000abc123xyz",
  "status": "running"
}
```

The initial status is typically `"running"` (not `"pending"`) because the agent starts immediately.

---

### POST /api/read (SIWX auth, free)

Read the current status of a run. Call it repeatedly every ~5 seconds until `status` is `completed` or `failed`.

**Input:**
```json
{
  "runId": "clx8m2k4p0000abc123xyz",
  "includeFiles": false
}
```

`includeFiles` is optional (default `false`). Set to `true` to list files currently in the run's sandbox volume. Only meaningful once the run has completed.

**Output (polling, `includeFiles: false`):**
```json
{
  "id": "clx8m2k4p0000abc123xyz",
  "status": "running",
  "errorCode": null,
  "createdAt": "2026-03-02T12:00:00.000Z",
  "updatedAt": "2026-03-02T12:00:10.000Z",
  "logs": null
}
```

**Output (after completion, `includeFiles: true`):**
```json
{
  "id": "clx8m2k4p0000abc123xyz",
  "status": "completed",
  "errorCode": null,
  "createdAt": "2026-03-02T12:00:00.000Z",
  "updatedAt": "2026-03-02T12:01:30.000Z",
  "logs": {
    "metadata": {
      "sessionId": "...",
      "startedAt": "2026-03-02T12:00:05.000Z",
      "completedAt": "2026-03-02T12:01:28.000Z",
      "model": "claude-sonnet-4-6"
    },
    "records": [ ... ]
  },
  "files": [
    { "path": "output.md", "type": "file", "size": 9422 },
    { "path": "data/", "type": "directory", "size": 0 }
  ]
}
```

`files` is only present when `includeFiles` is `true`. File paths are relative to the agent's workspace root and have no leading slash.

`logs` may be `null` early in a run — log ingestion is asynchronous and can lag behind status. Keep polling if `logs` is null; they will arrive shortly. Do not treat a null `logs` field as an error.

---

### POST /api/list (SIWX auth, free)

List runs for the authenticated wallet, ordered by most recently updated.

**Input:**
```json
{
  "limit": 10,
  "offset": 0
}
```

Both fields are optional. `limit` defaults to `10`, max `100`. `offset` defaults to `0`.

**Output:**
```json
{
  "runs": [
    {
      "id": "clx8m2k4p0000abc123xyz",
      "status": "completed",
      "errorCode": null,
      "createdAt": "2026-03-02T12:00:00.000Z",
      "updatedAt": "2026-03-02T12:01:30.000Z"
    }
  ]
}
```

---

### POST /api/file-url (SIWX auth, free)

Generate a presigned download URL for a file produced by a completed run. Get the available `path` values by calling `POST /api/read` with `includeFiles: true` first.

**Input:**
```json
{ "runId": "clx8m2k4p0000abc123xyz", "path": "declaration.md" }
```

The `path` should match what `/api/read` returned. Leading slashes are stripped server-side, so both `"output.md"` and `"/output.md"` work.

**Output:**
```json
{
  "url": "https://giga.dev/api/file?token=<signed-token>",
  "expiresAt": "2026-03-03T18:00:00.000Z"
}
```

The URL expires in 1 hour. Pass it directly to any HTTP client — no auth headers needed.

---

### GET /api/file (no auth — token is the credential)

Downloads a file using a presigned token issued by `/api/file-url`.

**Query params:** `?token=<signed-token>`

Returns the raw file content with `Content-Disposition: attachment` headers. Use this URL directly in a browser, `curl`, or `fetch` — no SIWX signature needed.

The token encodes the run ID, file path, and expiry. It cannot be forged without the server secret and expires after 1 hour.

**Example (curl):**
```bash
# 1. List files in the completed run
FILES=$(curl -s -X POST https://giga.dev/api/read \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <siwx-token>" \
  -d '{"runId":"clx8m2k4p0000abc123xyz","includeFiles":true}')

# 2. Get a presigned download URL for a specific file
URL=$(curl -s -X POST https://giga.dev/api/file-url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <siwx-token>" \
  -d '{"runId":"clx8m2k4p0000abc123xyz","path":"declaration.md"}' \
  | jq -r .url)

# 3. Download the file — no auth needed
curl -L -o declaration.md "$URL"
```

---

## Agent Capabilities

The agent running your prompt has access to the agentcash MCP and all endpoints available through it. Costs are drawn from the agent's wallet funded by your run payment.

---

## Run Status Values

| Status      | Meaning                          |
|-------------|----------------------------------|
| `pending`   | Run queued, not yet started      |
| `running`   | Agent is actively executing      |
| `completed` | Run finished successfully        |
| `failed`    | Run encountered an error         |

---

## Authentication

**x402 (payment):** Used by `POST /api/start`. Your x402-compatible client receives a `402` response, fulfills payment in USDC on Base, and retries. No manual auth setup needed.

**SIWX (Sign-In With X):** Used by `POST /api/read`, `POST /api/list`, and `POST /api/file-url`. These endpoints are free but require wallet identity. Your SIWX-compatible client receives a `402` response with a challenge, signs it with your wallet, and retries with the signature as a Bearer token.

**Token (no auth):** `GET /api/file` requires no auth headers. The signed token in the query string is the credential — it encodes the run ID, path, and expiry and cannot be forged.

---

## Notes

- Payments use x402 protocol with USDC on Base (`eip155:8453`)
- Call `POST /api/read` every ~5 seconds while `status` is `pending` or `running`
- File data sent to `/api/start` must be base64-encoded; filenames are sanitized and truncated to 255 chars