---
version: 1.0.0
name: firestarter-commerce
description: |
  Execute real-world purchases on behalf of users. Use when the user says "buy me", "order", "find and purchase", "restock", "procure", "get me", or asks to shop, compare products, or complete a transaction. Handles the full lifecycle: search, compare, approve, pay, ship, track.
allowed-tools:
  - Bash(npx:*)
  - Bash(curl:*)
metadata:
  author: firestarter
  url: firestarter.network
user-invocable: true
---

# Firestarter - Commerce Execution for Agents

Buy anything on behalf of a user. One API call handles: product search, supplier comparison, pricing, human approval, payment, shipping, tracking, and proof of delivery.

## Installing

### MCP Server (recommended)

Add to your MCP client config (`.mcp.json`, Claude Code settings, Cursor, etc.):

```json
{
  "mcpServers": {
    "firestarter": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.firestarter.network/.well-known/mcp.json"],
      "env": {
        "FIRESTARTER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Or use the API directly (no MCP required) - see Direct API below.

### Direct API

```bash
curl -X POST https://api.firestarter.network/v1/executions \
  -H "Authorization: Bearer fs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request": "noise cancelling headphones under $80"}'
```

Get an API key at https://firestarter.network/dashboard (tab: API Keys).

## Available tools

| Tool | Description |
|------|-------------|
| `firestarter_execute` | Start a purchase. Natural language in, product options out. |
| `firestarter_approve` | Approve an execution and trigger payment. |
| `firestarter_cancel` | Cancel an execution. Refunds automatically if payment was held. |
| `firestarter_status` | Check execution status or list recent executions. |
| `firestarter_message` | Refine a search mid-execution (e.g. "I want organic only"). |

## Core flow

- Step 1: Execute a purchase request
- Step 2: Review options with the user
- Step 3: Approve (triggers payment + shipping)
- Step 4: Track until delivered

### Step 1: Execute a purchase request

```bash
curl -X POST https://api.firestarter.network/v1/executions \
  -H "Authorization: Bearer $FIRESTARTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "wireless earbuds under $50, prioritize quality",
    "budget": {"max_total": 50, "currency": "USD"},
    "preferences": {
      "priority": "quality",
      "require_approval": true
    }
  }'
```

The API returns an execution ID and begins searching. Poll with `GET /v1/executions/:id` or use the MCP `firestarter_status` tool.

### Step 2: Review options

When status reaches `awaiting_approval`, the execution has product options:

```json
{
  "status": "awaiting_approval",
  "options": [
    {
      "product_title": "Sony WH-CH720N",
      "unit_price": 79.99,
      "match_score": 90,
      "store": "Amazon"
    }
  ]
}
```

Present these to the user. They choose which option to approve.

### Step 3: Approve

```bash
curl -X POST https://api.firestarter.network/v1/executions/:id/approve \
  -H "Authorization: Bearer $FIRESTARTER_API_KEY"
```

This triggers: payment authorization (Stripe escrow, manual capture) then shipping label creation. Payment is only captured on delivery confirmation.

### Step 4: Track

Poll `GET /v1/executions/:id` for status updates. Terminal states: `completed`, `failed`, `cancelled`.

The execution moves through: `finding` > `awaiting_approval` > `approved` > `paid` > `shipping` > `delivered` > `completed`.

## Payment with Stripe Link (optional)

For purchases where the user pays with their own card (not platform credits), Firestarter supports Stripe Link for agent-approved payments.

**Prerequisites:** Install the Link CLI alongside Firestarter:

```json
{
  "mcpServers": {
    "firestarter": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.firestarter.network/.well-known/mcp.json"],
      "env": {"FIRESTARTER_API_KEY": "YOUR_API_KEY"}
    },
    "link": {
      "command": "npx",
      "args": ["@stripe/link-cli", "--mcp"]
    }
  }
}
```

**Combined flow:**

1. Use `firestarter_execute` to find products and get options with pricing
2. Use Link CLI `spend-request create` to request payment approval from the user:
   - Set `--merchant-name` to the supplier name from the execution options
   - Set `--amount` to the total in cents
   - Set `--context` to describe the purchase (min 100 chars)
   - Set `--request-approval` to notify the user
3. User approves on their phone (Link app) or via the browser approval URL
4. Retrieve the one-time virtual card from the approved spend request
5. Use the virtual card to complete checkout at the merchant

Firestarter handles product discovery and comparison. Link handles secure payment credential issuance. The user's real card numbers are never exposed. The virtual card is single-use and expires in 12 hours.

**Limits:** $500 max per transaction, $500 daily. US Link accounts only (currently).

## Request body reference

| Field | Type | Description |
|-------|------|-------------|
| `request` | string | Natural language purchase request (required) |
| `budget.max_total` | number | Maximum spend in USD |
| `budget.currency` | string | ISO currency code (default: USD) |
| `preferences.priority` | string | `cost`, `speed`, or `quality` |
| `preferences.require_approval` | boolean | If true, holds for human approval before payment |
| `delivery_address` | object | Shipping destination |

## Execution lifecycle

| Status | Meaning |
|--------|---------|
| `finding` | Searching for products |
| `awaiting_approval` | Options found, waiting for human approval |
| `approved` | Approved, processing payment |
| `paid` | Payment authorized (escrow hold) |
| `shipping` | Label created, in transit |
| `delivered` | Delivery confirmed |
| `completed` | Payment captured, execution complete |
| `failed` | Something went wrong (check steps for details) |
| `cancelled` | Cancelled by user, payment voided |

## Governance and safety

- **Every purchase requires approval** unless `require_approval: false` and within budget
- **Budget enforcement** - execution fails before payment if over budget
- **Escrow payments** - funds are held, not captured, until delivery is confirmed
- **Full audit trail** - every step records agent reasoning, timestamps, and outcomes
- **Automatic refunds** - cancellation voids the payment hold instantly
- **Scoped API keys** - create keys with limited permissions per agent

## Billing

| Plan | Tokens | Price | Fee |
|------|--------|-------|-----|
| Free | 100 | $0 | 5% + 50¢ |
| Pro | 10,000/mo | $99/mo | 5% + 50¢ |
| Enterprise | Custom | Custom | Custom |

Each execution costs ~10 tokens. Check balance: `GET /v1/billing/balance`.

## Error codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad request - check body |
| 401 | Invalid or missing API key |
| 404 | Resource not found |
| 409 | Conflict - execution already in this state |
| 429 | Rate limited |
| 500 | Server error - retry |

## Getting help (agent-accessible support)

If an execution is stuck, billing looks wrong, or you hit unexpected behavior, file a support ticket directly with your API key — same Bearer auth as every other endpoint. A human reads every ticket. (The `/admin` prefix is historical; these endpoints work for any authenticated account.)

```bash
# open a ticket
curl -X POST https://api.firestarter.network/admin/tickets \
  -H "Authorization: Bearer $FIRESTARTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Execution stuck", "message": "exec_abc123 has been in finding for 2 hours."}'
# -> {"id": "tkt_xxxxxxxx", "status": "open"}

# list your tickets
curl https://api.firestarter.network/admin/my-tickets \
  -H "Authorization: Bearer $FIRESTARTER_API_KEY"

# read the thread (support replies appear here)
curl https://api.firestarter.network/admin/my-tickets/tkt_xxxxxxxx/messages \
  -H "Authorization: Bearer $FIRESTARTER_API_KEY"

# reply / add context
curl -X POST https://api.firestarter.network/admin/my-tickets/tkt_xxxxxxxx/reply \
  -H "Authorization: Bearer $FIRESTARTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Adding context: the order id is ord_456."}'
```

Include execution IDs (`exec_...`) and order IDs (`ord_...`) in the message so support can act immediately. Poll the messages endpoint for replies — there is no ticket webhook yet.

## Links

- Dashboard: https://firestarter.network/dashboard
- API Docs: https://firestarter.network/docs
- OpenAPI Spec: https://api.firestarter.network/.well-known/openapi.json
- MCP Manifest: https://api.firestarter.network/.well-known/mcp.json
- Examples: https://firestarter.network/examples