Choose an agent checkout path

Start with hosted buyer checkout, pay that URL with Tempo MPP, or adopt MCP when the agent needs direct control.

Start with a canonical product URL and hosted buyer checkout. Use Machine Payments Protocol (MPP) when the checkout advertises a payment endpoint. Use Model Context Protocol (MCP) when your agent needs to update checkout state directly.

Choose the control level

Need	Start with	Payment owner
Buy one known product	`purchaseWithAgent(productUrl)`	Hosted buyer
Pay one hosted checkout by wallet	Buyer checkout `mpp.endpoint`	Tempo wallet policy
Control checkout with an agent	Global Orderboost `/mcp` resource	Agent after exact human approval
Pay another advertised resource	Conforming MPP or x402 client	Agent payment-method policy

Use Tempo MPP only when the buyer-checkout response includes mpp.endpoint. Other MPP and x402 resources require their own advertised endpoint and request schema.

Install the agent SDK

Add Orderboost when the runtime controls the purchase in TypeScript:

npm install @orderboost/sdk

pnpm add @orderboost/sdk

yarn add @orderboost/sdk

bun add @orderboost/sdk

Open hosted buyer checkout

The Node helper looks up the exact product, opens one hosted page, polls read-only status, and returns the persisted order identifier.

import { purchaseWithAgent } from "@orderboost/sdk/agent/node";

const { orderId } = await purchaseWithAgent("https://merchant.example/products/arc?Color=Gray", {
	apiBaseUrl: "https://api.orderboost.example",
	quantity: 1,
});

The person enters buyer and payment details in the hosted page. The agent doesn’t call complete_checkout.

Connect an MCP host

Orderboost exposes one global MCP resource across registered merchants. Catalog search and lookup are anonymous. The first protected cart, checkout, or handoff tool triggers OAuth.

Choose one connection mode:

Mode	Use it when	Authorization URL owner
Direct remote MCP	The host implements remote MCP OAuth	Host callback and PKCE state
Local `orderboost-mcp` companion	The host can run a local stdio server	Companion returns the exact URL as tool text

Configure the portable companion in a client that supports a local MCP command:

{
	"orderboost": {
		"command": "orderboost-mcp",
		"args": [
			"--url",
			"https://mcp.orderboost.example/mcp",
			"--account-origin",
			"https://account.orderboost.example"
		]
	}
}

Install the companion on the agent host before using this configuration. Follow Authenticate an MCP client for installation, native OAuth, and the connection-code flow.

Run direct checkout through MCP

Follow the protected checkout lifecycle:

Find the product

Call search_catalog, lookup_catalog, or get_product. Pass canonical product URLs into checkout creation.

Authenticate protected tools

Use native OAuth or the companion’s exact browser URL. Finish fresh account authentication and consent before using the separate connection code.

Create checkout

Call create_cart or create_checkout. Treat the returned items, total, revision, and status as authoritative.

Request human approval

Open the exact continue_url when the checkout returns requires_escalation.

Complete once

Refresh with get_checkout, then call complete_checkout with the purchase grant and one stable idempotency key.

Never ask for passwords, email verification codes, OAuth tokens, payment credentials, or a handoff code for a new purchase.

Pay the hosted URL with Tempo MPP

Post the product URL to POST /api/v1/buyer-checkouts. When the response contains mpp.endpoint, an authorized machine wallet can post the exact checkoutUrl there. Orderboost first returns any missing buyer, billing, fulfillment, and shipping-option paths without requesting payment. The complete request uses one Idempotency-Key; Orderboost requotes before returning an exact Tempo charge challenge.

The paid retry must use the identical endpoint, body, and key. Require Payment-Receipt, completed checkout state, and orderId. The caller never supplies amount, recipient, quote hash, purchase grant, or a separate completion request.

For a paid page or API that is not this commerce checkout, call only the resource endpoint its live documentation advertises. Orderboost does not currently ship built-in x402 checkout settlement.

Follow Pay a hosted checkout with Tempo MPP for the client flow. Read Understand agentic checkout for the MCP, MPP, and x402 boundaries.