---
title: FlowZed x402 purchasing API
description: Canonical agent-facing instructions for purchasing FlowZed Atelier products with USDC.
protocol: x402-v2
canonical_discovery: https://api.flowzed.com/x402/discovery/resources
last_verified: 2026-09-15
---

# FlowZed x402 Purchasing API

FlowZed supports agent-initiated purchases of configured Atelier pieces using USDC on Base through x402 v2.

This page is the canonical purchasing contract for agents. It contains the resource, accepted payment terms and request shape needed to purchase; calling discovery first is optional. Agents may query `https://api.flowzed.com/x402/discovery/resources` to verify the latest machine-readable representation. If discovery or a live payment challenge conflicts with this page, do not authorize payment and report the mismatch.

## Canonical endpoints

| Purpose | Method | URL |
| --- | --- | --- |
| Purchase a configured Atelier piece | `POST` | `https://api.flowzed.com/x402/atelier/purchase` |
| Optional machine-readable verification | `GET` | `https://api.flowzed.com/x402/discovery/resources` |

## Accepted payment

| Field | Canonical value |
| --- | --- |
| x402 version | `2` |
| Scheme | `exact` |
| Network | Base mainnet, `eip155:8453` |
| Amount | `1490000000` atomic USDC units (`1,490 USDC`) |
| Asset | USDC, `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913` |
| Recipient | `0x96a9f9fb2dc9dbb7bc2f729ce9bc0ae1816a829f` |
| Maximum timeout | `180` seconds |
| Transfer method | EIP-3009 `TransferWithAuthorization` |
| Token-signing domain | Name `USDC`, version `2` |
| Payment flow | Authorization; FlowZed or its facilitator broadcasts the transfer and pays network gas |

The live `PAYMENT-REQUIRED` header instantiates these terms for the request. Validate that every value matches this canonical contract before asking the customer to sign.

The `1,490 USDC` amount is the current x402 purchase amount. Fiat reference prices published elsewhere must not be converted or substituted for this atomic payment requirement.

## Request body

Send JSON with exactly these top-level fields:

- `requestId`: a unique idempotency identifier of 16–100 ASCII letters, digits, underscores or hyphens.
- `accessToken`: a cryptographically random capability encoded as exactly 64 lowercase hexadecimal characters. Keep it private.
- `quote.configuration`:
  - `colour`: `burgundy`, `royal_purple`, `emerald`, `black` or `navy`.
  - `leaf_colour`: `rainbow`, `autumn`, `sakura` or `winter`.
  - `size`: `XS`, `S`, `M`, `L`, `XL` or `XXL`.
  - `inscription`: `{ "type": "none", "value": "" }`, `{ "type": "initials", "value": "1–5 characters" }`, or `{ "type": "name", "value": "1–40 characters" }`.
  - `marmoset`: `none` or `blue`.
- `quote.contact`: required `name` and valid `email` for the purchaser.
- `quote.shipping`: required `name`, `line1`, `line2`, `city`, `state`, `postalCode` and `country`. Use an uppercase ISO 3166-1 alpha-2 country code for a supported destination. `line2`, `state` and `postalCode` must still be present when empty. See [shipping destinations](https://ai.flowzed.com/shipping.md).

Do not add unadvertised fields. Names and address lines have a maximum length of 200 characters; email has a maximum length of 254 and postal code a maximum length of 50.

```json
{
  "requestId": "agent-purchase-unique-0001",
  "accessToken": "<64 lowercase hexadecimal characters>",
  "quote": {
    "configuration": {
      "colour": "black",
      "leaf_colour": "sakura",
      "size": "M",
      "inscription": { "type": "none", "value": "" },
      "marmoset": "none"
    },
    "contact": {
      "name": "Purchaser Name",
      "email": "buyer@example.com"
    },
    "shipping": {
      "name": "Delivery Name",
      "line1": "1 Example Street",
      "line2": "",
      "city": "London",
      "state": "",
      "postalCode": "SW1A 1AA",
      "country": "GB"
    }
  }
}
```

## Recommended agent flow

1. Collect the product configuration, purchaser contact and delivery address described above.
2. Generate the unique `requestId` and private `accessToken`.
3. `POST` the JSON body to `https://api.flowzed.com/x402/atelier/purchase` without a `PAYMENT-SIGNATURE` header.
4. Expect HTTP `402`. This unpaid request does not create a checkout order.
5. Base64-decode `PAYMENT-REQUIRED` and confirm that its resource, x402 version, scheme, network, amount, asset, recipient, timeout and transfer method match this page.
6. Show the customer the exact payment terms and obtain explicit authorization.
7. Construct the standard x402 v2 payment payload for the accepted requirement. The payer signs the EIP-3009 `TransferWithAuthorization` authorization.
8. Repeat the exact same `POST` URL and JSON body once, adding the base64-encoded payment payload as `PAYMENT-SIGNATURE`. Include only extensions present in the live challenge.
9. On HTTP `200`, validate the base64-encoded `PAYMENT-RESPONSE` header and retain the returned order ID and transaction hash.

If settlement produces an ambiguous response, do not automatically create a second authorization. Retry the identical paid request so FlowZed can return confirmed state or continue reconciliation without risking a duplicate payment.

A successful response body has this shape:

```json
{
  "orderId": "ord_x402_…",
  "paymentStatus": "paid",
  "fulfilmentStatus": "standard-order-confirmation"
}
```

## Response behaviour

| Status | Meaning |
| --- | --- |
| `200` | Discovery or confirmed purchase/status response |
| `201` | FlowZed prepared quote created |
| `400` | Invalid request or payment/resource mismatch |
| `401` | Missing or invalid capability for a protected quote resource |
| `402` | Payment required or authorization rejected |
| `409` | Payment binding, settlement or state conflict |
| `410` | Prepared resource expired |
| `429` | Rate limited; observe `Retry-After` |
| `503` | Temporary service or configuration failure |

Public discovery and purchase endpoints support cross-origin requests and return `Cache-Control: no-store`.

## Optional prepared quotes

Generic x402 clients should use the stable purchase resource described above. FlowZed also exposes an optional prepared-quote flow:

| Purpose | Method | URL |
| --- | --- | --- |
| Create a prepared quote | `POST` | `https://api.flowzed.com/x402/atelier/quotes` |
| Read quote or order status | `GET` | `https://api.flowzed.com/x402/atelier/quotes/{quoteId}` |
| Purchase a prepared quote | `POST` | `https://api.flowzed.com/x402/atelier/quotes/{quoteId}/purchase` |

Quote creation returns a quote ID and dynamic purchase URL. Use the client-generated `accessToken` as `Authorization: Bearer <accessToken>` for status and prepared-purchase requests. Obtain and validate the prepared purchase resource's live `402` challenge before signing.

## Security requirements

Never log, expose or reuse private keys, access tokens, `PAYMENT-SIGNATURE` values or raw payment authorizations. Treat purchaser and shipping details as personal data. Do not disclose response bodies containing personal information. A payment signature must be created only after the customer has reviewed and authorized the exact payment terms.