MixR Agent API

Build intelligent shopping agents with MixR's comprehensive API

Base URL

https://mixr.gg/server/api

Version

Authentication

None

Agent API

/v1/agent

Try the MixR Agent

Test the Agent API with our interactive tool. Experiment with different checkout flows and see real-time responses.

Open Agent Tool

Overview

The MixR Agent API enables developers to build intelligent shopping agents that can browse products, create checkout intents, and complete purchases on behalf of users. The API supports two checkout flows: Rye Universal Checkout for external retailers and Native Checkout for MixR catalog products.

Agent Capabilities

Get Agent Capabilities

Retrieve the current capabilities of the agent API. This endpoint provides information about supported payment methods, fulfillment types, and future capabilities.

GET/v1/agent/capabilities

Agent Note: Call this at the start of your session to understand system capabilities. Check requiresHumanPayment to determine if human payment authorization is needed. Check supportedPaymentAuthorizationTypes to see available payment methods.

Response Fields

requiresHumanPayment - Whether human payment authorization is currently required
supportedPaymentAuthorizationTypes - Payment authorization types currently supported
supportedFulfillmentTypes - Fulfillment types available
supportedCheckoutTypes - Checkout types supported
futureCapabilities - Capabilities planned for future releases

Quick Start Guide

Understanding walletAddress vs buyer Details

For MixR Platform Users:

User provides their walletAddress to the agent
Agent includes walletAddress in API requests
API automatically fetches buyer details (name, email, phone, address) from user's stored profile
No need to collect or send buyer information - just send walletAddress

For External/Guest Users:

User does not have a MixR account or wallet address
Agent collects buyer details directly from user (via conversation/input)
Agent includes complete buyer object in API requests
Must provide all required buyer fields (firstName, lastName, email, phone, address, etc.)

Choosing Your Checkout Flow

Rye Universal Checkout

Use when purchasing from external retailers (Amazon, Walmart, Target, etc.)

Flow: Browse → Get Product → Create Intent → Confirm Payment → Save Order

Native Checkout

Use when purchasing MixR catalog products with variant IDs

Flow: Browse → Create Cart → Prepare Checkout → Submit Payment

Essential Steps for Agents

For Rye Universal Checkout:

Get product url from product response
Get buyer details:
- MixR Platform Users: Provide walletAddress to auto-fill buyer details
- External/Guest Users: Provide complete buyer information
Create checkout intent with productUrl and buyer info (or walletAddress)
Check purchaseIntent.intentState - if "awaiting_payment", proceed
Confirm with payment authorization
Save order details

For Native Checkout:

Get variantId from product variants
Create cart:
- MixR Platform Users: Include walletAddress to link cart to account
- Anonymous/Guest Users: Omit walletAddress, cart created as guest
Prepare checkout with buyer details:
- MixR Users with walletAddress: Details auto-filled, just use autoSelectShipping: true
- Anonymous Users: Provide complete buyer information with autoSelectShipping: true
Check readyForCheckout - if true, proceed
Submit payment

Key Decision Fields:

purchaseIntent.intentState - Authoritative state for decision-making
purchaseIntent.nextActionRequired - What action to take next
readyForCheckout - Whether checkout is ready (Native only)

Product Browsing

List Products

Browse and search products available on MixR

GET/v1/agent/products

Key Query Parameters

keyword - Search keyword
category - Filter by category
priceMin / priceMax - Price range in cents
page / limit - Pagination

Agent Tip: Check agentMetadata.isPurchasable to filter purchasable products. Extract url for Rye checkout or variants[].id for Native checkout.

Get Single Product

Retrieve detailed information about a specific product

GET/v1/agent/products/:id

Checkout (Rye Universal)

walletAddress Parameter - Complete Reference

The walletAddress parameter allows MixR platform users to automatically fetch their stored buyer details. Here's how it works across all endpoints:

Endpoint	Method	walletAddress Location	Required?	Effect
/v1/agent/checkout	POST	Request Body	No (optional)	Auto-fills all buyer details from user profile
/v1/agent/checkout/:id	GET	Query Parameter	No (optional)	Includes buyer details in response
/v1/agent/checkout/:id/confirm	POST	Request Body	No (optional)	For tracking purposes (MixR users)
/v1/agent/native/cart	POST	Request Body	No (optional)	Links cart to user account
/v1/agent/native/checkout/prepare	POST	Request Body	No (optional)	Auto-fills all buyer details from user profile
/v1/agent/native/checkout/submit	POST	Request Body	No (optional)	For tracking purposes (MixR users)
/v1/agent/native/checkout/:id/status	GET	Query Parameter	No (optional)	For tracking purposes (MixR users)
/v1/agent/orders/save	POST	Request Body	No (optional)	Auto-fills all buyer details from user profile

Key Points:

POST endpoints: Include walletAddress in the request body
GET endpoints: Include walletAddress as a query parameter (e.g., ?walletAddress=0x...)
When provided: All buyer details are automatically filled from user's stored profile
When omitted: Complete buyer information must be provided in the buyer object

How Agents Get Buyer Details

Using walletAddress for MixR Users (Recommended - Simplest)

If the user is a MixR platform user with a wallet address, simply provide walletAddress in the request. All buyer details are automatically filled from the user's profile and default shipping address stored on MixR. No need to send buyer object - just send walletAddress and the API handles everything.

Collecting from External/Guest Users Directly

If the user is not a MixR user (external/guest checkout), collect buyer details directly from the user (via conversation/input). The agent then includes complete buyer information in the buyer object.

Note: The API does not provide a way to "look up" or "search" for users. For MixR users, the agent must have the user's wallet address. For external users, collect buyer details directly.

Create Checkout Intent

Creates a checkout intent with Rye Universal Checkout using a product URL

POST/v1/agent/checkout

Request Parameters

productUrl (required) - Product URL from supported retailer
quantity (required) - Quantity to purchase (minimum: 1)
walletAddress (optional) - Wallet address for MixR users (auto-fills buyer details)
buyer (conditionally required) - Buyer information (required if walletAddress not provided)

Request Body (MixR user with walletAddress - simplest)

Code

{
  "productUrl": "https://www.amazon.com/dp/B08N5WRWNW",
  "quantity": 1,
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

Request Body (External/guest user - complete buyer details)

Code

{
  "productUrl": "https://www.amazon.com/dp/B08N5WRWNW",
  "quantity": 1,
  "buyer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+15551234567",
    "address1": "123 Main Street",
    "city": "San Francisco",
    "province": "CA",
    "country": "US",
    "postalCode": "94102"
  }
}

Agent Note: After creating intent, check purchaseIntent.intentState. If "awaiting_payment", proceed to confirm endpoint.

Get Checkout Intent

Retrieves the current state of a checkout intent

GET/v1/agent/checkout/:checkoutIntentId

Query Parameters

walletAddress (optional) - If provided, buyer details are included in response (MixR users only)

Example: GET /v1/agent/checkout/ci_abc123?walletAddress=0x742d35Cc...

Confirm Checkout Intent

Confirms payment and completes the order

POST/v1/agent/checkout/:checkoutIntentId/confirm

Request Parameters

walletAddress (optional) - Wallet address for tracking purposes (MixR users)
paymentAuthorization (required) - Payment authorization object

Request Body

Code

{
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "paymentAuthorization": {
    "type": "stripe_token",
    "token": "tok_visa_4242424242424242"
  }
}

Agent Note: Check purchaseIntent.intentState after confirmation. If "completed", proceed to save order. If "processing", wait and check status. If "failed", handle error.

Native Checkout

Key Advantages

Optimized Flow: Combines address + shipping fetch + shipping selection in one call
Auto-Selection: Option to automatically select first shipping method
Reduced API Calls: Fewer round trips compared to Rye Universal Checkout
Native Integration: Uses MixR's cart system directly
Supports Both User Types: Works for both MixR platform users and anonymous/guest users

Create Native Cart

Creates a cart and adds items for native checkout

POST/v1/agent/native/cart

Request Parameters

items (required) - Array of items with variantId and quantity
walletAddress (optional) - Links cart to user account (MixR users only)
agentSessionId (optional) - Agent session identifier

Request Body Example

Code

{
  "items": [
    {
      "variantId": "variant_123",
      "quantity": 1
    }
  ],
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

Agent Note: Save cartId from response - required for all subsequent native checkout calls. walletAddress is optional - provide it for MixR users to link cart to their account (enables features like order history). For anonymous/guest users, omit walletAddress and provide buyer details in the prepare checkout step.

Prepare Native Checkout

Combines multiple steps in one call: Adds shipping address, fetches shipping options, and optionally auto-selects shipping methods.

POST/v1/agent/native/checkout/prepare

Request Parameters

cartId (required) - Cart ID from create cart response
walletAddress (optional) - Auto-fills all buyer details from user profile (MixR users)
buyer (conditionally required) - Required if walletAddress not provided
autoSelectShipping (optional) - Auto-selects first shipping method (default: false)

Request Body (MixR user with walletAddress - simplest)

Code

{
  "cartId": "42",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "autoSelectShipping": true
}

Agent Note: Use autoSelectShipping: true to automatically select first shipping method. Check readyForCheckout - if true, proceed to submit endpoint.

Note: When walletAddress is provided (MixR users), the buyer object is completely optional. All buyer details are automatically fetched from the user's profile. For anonymous users, omit walletAddress and provide complete buyer details.

Submit Native Checkout

Submits payment and completes the checkout

POST/v1/agent/native/checkout/submit

Request Parameters

cartId (required) - Cart ID
walletAddress (optional) - For tracking purposes (MixR users)
payment (required) - Payment authorization object
agentSessionId (optional) - Agent session identifier

Request Body Example

Code

{
  "cartId": "42",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "payment": {
    "type": "stripe_token",
    "token": "tok_visa_4242424242424242"
  }
}

Agent Note: Check status field in response. If "SUCCEEDED", order is complete. If "PROCESSING", check status endpoint.

Get Native Checkout Status

Retrieves the current status of a checkout

GET/v1/agent/native/checkout/:cartId/status

Query Parameters

walletAddress (optional) - Wallet address for tracking purposes (MixR users)

Example: GET /v1/agent/native/checkout/42/status?walletAddress=0x742d35Cc...

Order Management

Save Order

Saves order details to the database after successful checkout

POST/v1/agent/orders/save

Request Parameters

checkoutIntentId (required) - Rye checkout intent ID
walletAddress (optional) - Auto-fills all buyer details from user profile (MixR users)
buyer (conditionally required) - Required if walletAddress not provided
product (required) - Product information
pricing (required) - Pricing structure
orderState (required) - Must match purchaseIntent.intentState

Important: The orderState field must match the final purchaseIntent.intentState from the checkout intent. Mismatch will result in ORDER_STATE_MISMATCH error.

Note: When walletAddress is provided (for MixR users), the buyer object is completely optional. All buyer details are automatically fetched from the user's profile stored on MixR platform.

Error Handling

Error Response Format

Code

{
  "error": "Human-readable error message",
  "errorCode": "MACHINE_READABLE_CODE",
  "details": "Additional technical details (optional)"
}

Common Error Codes

PAYMENT_REQUIRED

Payment authorization is required

CHECKOUT_NOT_READY

Checkout intent creation failed

INVALID_BUYER_INFO

Buyer information is invalid or incomplete

INVALID_PAYMENT_AUTHORIZATION

Payment authorization format is invalid

PRODUCT_UNAVAILABLE

Product is not available for purchase

INVALID_PRODUCT_URL

Product URL is invalid or unsupported

ADDRESS_REQUIRED

Shipping address is required

SHIPPING_NOT_SELECTED

Shipping method must be selected

CHECKOUT_FAILED

Checkout processing failed

INTENT_NOT_FOUND

Checkout intent not found

ORDER_STATE_MISMATCH

Order state does not match purchase intent

INTERNAL_ERROR

Internal server error

VALIDATION_ERROR

Request validation failed

Important Notes for Agents

Wallet Address and Buyer Details

How Agents Get Buyer Details:

From MixR User Wallet Address (Recommended for MixR Users):
- If the user is a MixR platform user, use their walletAddress
- Provide walletAddress in request body (POST) or query parameter (GET)
- The API automatically fetches buyer details from the user's profile and default shipping address stored on MixR platform
- This ensures data consistency and reduces the need to collect information from users
Direct Collection from External/Guest Users:
- If the user is not a MixR user (external/guest checkout), collect buyer details directly from the user
- Ask the user for: name, email, phone, and shipping address
- Include complete buyer information in the request body
- The agent is responsible for data validation and formatting

Using walletAddress for Auto-Fill (Simplest Approach for MixR Users):

Just provide walletAddress - all buyer details are automatically fetched from user's profile and default shipping address on MixR platform
No need to send buyer object - the API handles everything automatically
Buyer object is completely optional when walletAddress is provided
If you do provide buyer fields, they override the auto-filled data (useful for using a different address)
If walletAddress is not provided, complete buyer information must be included in the buyer object

Decision-Making Fields

purchaseIntent.intentState - Authoritative state:

"created" → Wait, system preparing
"awaiting_payment" → Ready for payment
"processing" → Payment processing, wait
"completed" → Success, proceed to save order
"failed" → Handle error

purchaseIntent.nextActionRequired - What to do next:

"awaiting_human_payment" → Submit payment
"awaiting_offer_preparation" → Wait for system
"processing_payment" → Wait for processing
"none" → No action needed (completed)
"retry_or_cancel" → Handle failure

readyForCheckout (Native only) - Whether checkout is ready:

true → Proceed to payment
false → Shipping not selected (shouldn't happen with autoSelectShipping: true)

Optimization Tips

Use walletAddress: For MixR users, use walletAddress to reduce request payload size and ensure consistency
Native Checkout: Always use autoSelectShipping: true in prepare step
Save IDs: Always save checkoutIntentId (Rye) or cartId (Native) after creation
Check states: Always verify purchaseIntent.intentState before proceeding
Error Handling: Check errorCode field for programmatic error handling

Required Formats

Phone: Exactly 12 characters, format +1XXXXXXXXXX (e.g., +15551234567)
Country: Currently only US supported
Payment: Use paymentAuthorization format
Wallet Address: String format (Ethereum address), provided in request body (POST) or query parameter (GET) for MixR users

Order State Validation

When saving orders (POST /orders/save), orderState must match purchaseIntent.intentState:

If intent state is "completed" → Use orderState: "SUCCEEDED"
If intent state is "failed" → Use orderState: "FAILED"
If intent state is "processing" → Use orderState: "PROCESSING"

Mismatch will result in ORDER_STATE_MISMATCH error.

For questions or issues with the Agent API, please contact the MixR development team.

API Version: v1 • Last Updated: 2024-12-15

Endpoint

Method

walletAddress Location

Required?

Effect

/v1/agent/checkout

POST

Request Body

No (optional)

Auto-fills all buyer details from user profile

/v1/agent/checkout/:id

GET

Query Parameter

No (optional)

Includes buyer details in response

/v1/agent/checkout/:id/confirm

POST

Request Body

No (optional)

For tracking purposes (MixR users)

/v1/agent/native/cart

POST

Request Body

No (optional)

Links cart to user account

/v1/agent/native/checkout/prepare

POST

Request Body

No (optional)

Auto-fills all buyer details from user profile

/v1/agent/native/checkout/submit

POST

Request Body

No (optional)

For tracking purposes (MixR users)

/v1/agent/native/checkout/:id/status

GET

Query Parameter

No (optional)

For tracking purposes (MixR users)

/v1/agent/orders/save

POST

Request Body

No (optional)

Auto-fills all buyer details from user profile

{ "productUrl": "https://www.amazon.com/dp/B08N5WRWNW", "quantity": 1, "buyer": { "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+15551234567", "address1": "123 Main Street", "city": "San Francisco", "province": "CA", "country": "US", "postalCode": "94102" } }