Agent Checkouts Quickstart ⚡

const BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts";

const headers = {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.CROSSMINT_API_KEY!,
    "x-crossmint-user-id": "YOUR_USER_ID",
};

const response = await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
        request: {
            startUrl: "https://merchant.example/collections/shirts",
            task: "Buy one Classic Tee in black, size medium",
        },
        constraints: {
            maxCost: { amount: "100.00", currency: "USD" },
        },
    }),
});

if (!response.ok) {
    throw new Error(`Could not start checkout: ${response.status}`);
}

const { runId } = await response.json();

{
    "request": {
        "startUrl": "https://merchant.example/products/classic-tee-black-medium"
    },
    "constraints": {
        "maxCost": { "amount": "100.00", "currency": "USD" }
    }
}

curl --no-buffer \
    --url "https://www.crossmint.com/api/unstable/agent-checkouts/YOUR_RUN_ID/messages/stream" \
    --header "Accept: text/event-stream" \
    --header "X-API-KEY: YOUR_SERVER_API_KEY" \
    --header "x-crossmint-user-id: YOUR_USER_ID"

id: cursor_01
event: run.updated
data: {"runId":"...","revision":3,"status":"awaiting_input","requiredAction":{...}}

id: cursor_02
event: message.upsert
data: {"id":"msg_...","revision":2,"role":"assistant","parts":[...]}

// Uses BASE_URL and headers from the configure step.
let cursor: string | null = null;
let streamCursor: string | null = null;
const messages = new Map();
const answeredRequestIds = new Set<string>();

do {
    const query = new URLSearchParams({ limit: "100" });
    if (cursor) {
        query.set("cursor", cursor);
    }

    const response = await fetch(`${BASE_URL}/${runId}/messages?${query}`, { headers });
    if (!response.ok) {
        throw new Error(`Could not list checkout messages: ${response.status}`);
    }

    const page = await response.json();

    for (const message of page.data) {
        const existing = messages.get(message.id);
        if (!existing || message.revision > existing.revision) {
            messages.set(message.id, message);
        }
    }

    cursor = page.nextCursor;
    streamCursor = page.streamCursor;
} while (cursor);

// Read the run after history so an action that was already pending is not missed.
const runResponse = await fetch(`${BASE_URL}/${runId}`, { headers, cache: "no-store" });
if (!runResponse.ok) {
    throw new Error(`Could not read checkout: ${runResponse.status}`);
}

const currentRun = await runResponse.json();
const pendingAction = currentRun.requiredAction;
if (
    currentRun.status === "awaiting_input" &&
    pendingAction &&
    !answeredRequestIds.has(pendingAction.requestId)
) {
    await handleRequiredAction(runId, pendingAction);
    answeredRequestIds.add(pendingAction.requestId);
}

const TERMINAL_STATUSES = new Set(["succeeded", "blocked", "failed", "cancelled"]);
const answeredRequestIds = new Set<string>();
const RETRYABLE_READ_STATUSES = new Set([408, 429, 500, 502, 503, 504]);

const wait = (delayMs: number) => new Promise((resolve) => setTimeout(resolve, delayMs));

async function getRun(runId: string) {
    let retryDelayMs = 1_000;

    while (true) {
        let response: Response;

        try {
            response = await fetch(`${BASE_URL}/${runId}`, {
                headers,
                cache: "no-store",
            });
        } catch {
            await wait(retryDelayMs);
            retryDelayMs = Math.min(retryDelayMs * 2, 10_000);
            continue;
        }

        if (response.ok) {
            return response.json();
        }

        if (!RETRYABLE_READ_STATUSES.has(response.status)) {
            throw new Error(`Could not read checkout: ${response.status}`);
        }

        const rateLimitBody = response.status === 429 ? await response.json().catch(() => null) : null;
        const retryAfterSeconds = rateLimitBody?.retryAfterSeconds;
        const serverDelayMs =
            typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
                ? retryAfterSeconds * 1_000
                : 0;

        await wait(Math.max(retryDelayMs, serverDelayMs));
        retryDelayMs = Math.min(retryDelayMs * 2, 10_000);
    }
}

let run = await getRun(runId);
let pollDelayMs = 2_000;
let previousStatus = run.status;

while (!TERMINAL_STATUSES.has(run.status)) {
    const action = run.requiredAction;

    if (run.status === "awaiting_input" && action && !answeredRequestIds.has(action.requestId)) {
        await handleRequiredAction(runId, action);
        answeredRequestIds.add(action.requestId);
        pollDelayMs = 2_000;
    }

    await wait(pollDelayMs);
    run = await getRun(runId);

    pollDelayMs = run.status === previousStatus ? Math.min(pollDelayMs * 1.5, 5_000) : 2_000;
    previousStatus = run.status;
}

// Pseudocode - connect each branch to the corresponding UI in your app.
async function handleRequiredAction(runId: string, action) {
    switch (action.request.interaction.kind) {
        case "form":
            return renderSchemaForm(runId, action);
        case "payment":
            return authorizeAgentCard(runId, action);
        case "protected":
            return collectProtectedPassword(runId, action);
    }
}

async function sendInputResponse(runId: string, messageId: string, part: Record<string, unknown>) {
    const response = await fetch(`${BASE_URL}/${runId}/messages`, {
        method: "POST",
        headers,
        body: JSON.stringify({
            id: messageId,
            parts: [part],
        }),
    });

    if (!response.ok) {
        throw new Error(`Could not answer checkout: ${response.status}`);
    }
}

const messageId = crypto.randomUUID();

await sendInputResponse(runId, messageId, {
    type: "input_response",
    requestId: action.requestId,
    action: "submit",
    response: {
        kind: "form",
        values: {
            size: "M",
            color: "black",
        },
    },
});

{
    "id": "msg_7f3c9a",
    "parts": [
        {
            "type": "input_response",
            "requestId": "req_123",
            "action": "submit",
            "response": {
                "kind": "payment",
                "orderIntentId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890"
            }
        }
    ]
}

{
    "id": "msg_9d2e4b",
    "parts": [
        {
            "type": "input_response",
            "requestId": "req_456",
            "action": "submit",
            "response": {
                "kind": "protected",
                "protectedInputId": "5f0c2a9e-7b1d-4c3a-9e8f-2d6b4a1c0e7f"
            }
        }
    ]
}

await fetch(`${BASE_URL}/${runId}/messages`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        id: crypto.randomUUID(),
        parts: [
            {
                type: "text",
                text: "Use standard shipping, and choose navy if black is sold out.",
            },
        ],
    }),
});

switch (run.status) {
    case "succeeded": {
        const { summary, purchase } = run.result;
        if (purchase.kind === "receipt_captured") {
            const { total, merchantOrderId } = purchase.receipt;
        }
        break;
    }
    case "blocked": {
        const { summary, code } = run.result;
        break;
    }
    case "failed": {
        const { reason } = run;
        break;
    }
    case "cancelled":
        break;
}