---
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 | 3% |
| Pro | 10,000/mo | $99/mo | 3% |
| 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 |

## 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