# Synthetic Friends — Agent Interface

> Order anything with a text. Built for humans. Open to agents.

## What We Do

Synthetic Friends places food orders on behalf of users and AI agents.
Describe what you want in plain language — we find the restaurant, build the cart, and execute the order.

## Supported Restaurants

30+ restaurants and growing, including:

- Chipotle
- Torchy's Tacos
- Jimmy John's
- Chick-fil-A
- Starbucks
- Subway
- Whataburger
- McDonald's
- Five Guys
- Domino's
- Raising Cane's
- Wingstop
- Panda Express
- And many more

## Machine API

REST API for autonomous agents. Two ways to authenticate and pay.

### Discovery

```
GET /api/machine/discovery
```

Returns the list of available restaurants.

```
GET /api/machine/restaurants/{slug}/menu
```

Returns the full menu for a restaurant.

```
GET /api/machine/restaurants/{slug}/locations
```

Returns nearby locations for a restaurant.

### Pricing

```
GET /api/machine/pricing
```

Returns current per-operation pricing:

| Operation | Price | Description |
|-----------|-------|-------------|
| `quote` | $0.03 | Validate an order and get a price |
| `execute_dry_run` | $0.49 | Test order execution (no submission) |
| `execute_live` | $1.49 | Real order submission |

### Ordering Flow

#### 1. Get a quote

```
POST /api/machine/orders/quote
Content-Type: application/json
```

```json
{
  "restaurant": "chipotle",
  "items": [
    {
      "name": "Burrito Bowl",
      "customizations": ["Chicken", "Brown Rice", "Extra Guacamole"]
    }
  ],
  "location": {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX"
  }
}
```

#### 2. Execute the order

```
POST /api/machine/orders/execute
Content-Type: application/json
```

```json
{
  "restaurant": "chipotle",
  "items": [...],
  "location": {...},
  "mode": "live"
}
```

#### 3. Track status

```
GET /api/machine/orders/status/{order_run_id}
```

Returns order state, confirmation number, and ETA when available.

### Payment

Two ways to pay — choose what fits your agent:

#### Option A: API Key (for repeat agents)

Pre-register for an API key. Attach it to every request. Best for high-volume agents with an ongoing relationship.

```
X-Machine-Api-Key: your-api-key
```

Request access by joining the waitlist.

#### Option B: x402 (for zero-friction agents)

No account. No API key. Just pay and order.

We support the [x402 protocol](https://www.x402.org/) for machine-to-machine payments. Any agent can transact without pre-registration:

1. Send your order request to `POST /api/machine/orders/execute`
2. Receive a `402 Payment Required` response with pricing and payment details
3. Pay in **USDC on Base**
4. Retry the request with proof of payment
5. Order executes

```
Agent                          Synthetic Friends
  |                                    |
  |  POST /api/machine/orders/execute  |
  |----------------------------------->|
  |                                    |
  |  402 Payment Required              |
  |  X-Payment-Amount: 1.49            |
  |  X-Payment-Currency: USDC          |
  |  X-Payment-Network: base           |
  |  X-Payment-Address: 0x...          |
  |<-----------------------------------|
  |                                    |
  |  [pay on-chain]                    |
  |                                    |
  |  POST /api/machine/orders/execute  |
  |  X-Payment-Proof: {txHash}         |
  |----------------------------------->|
  |                                    |
  |  200 OK {order_id, eta, items}     |
  |<-----------------------------------|
```

Idempotency is supported via the optional `X-Idempotency-Key` header.

## Consumer API

Human users interact through our mobile app via conversational AI:

1. **Authenticate** — SMS verification, Google, or Apple sign-in
2. **Discover** — Find restaurants by food preference and location
3. **Chat** — Describe your order in plain language to our AI
4. **Confirm & Pay** — Review the cart, pay securely
5. **Track** — Real-time order status via push notifications

## Discovery

- **Agent manifest:** `/.well-known/agent.json`
- **This document:** `/agents`
- **Website:** [syntheticfriends.app](https://syntheticfriends.app)

## Status

- **Launch date:** July 1, 2026
- **Machine API:** Coming at launch
- **x402 payments:** Coming at launch
- **Waitlist API:** Live now

### Join the Waitlist

```
POST /api/waitlist
Content-Type: application/json
```

```json
{
  "email": "agent@example.com"
}
```

Returns `{ "success": true, "message": "Added to waitlist" }`

---

Built by [Synthetic Friends](https://syntheticfriends.app) // 2026