Hyperfold AI

Agentic Commerce Protocol (ACP)

The standard protocol for autonomous agent-to-merchant commerce interactions.

What is ACP?

The Agentic Commerce Protocol (ACP) is an open standard that defines how AI agents discover, negotiate, and purchase from merchants. It enables autonomous commerce where buyer agents can interact with seller agents without human intervention.

ACP is inspired by OpenAI's vision for agent commerce and is designed to work with any LLM-powered buying agent, not just specific platforms.

Key principles of ACP:

  • Semantic over syntactic: Natural language queries instead of keyword searches
  • Negotiation-first: Prices are starting points, not fixed values
  • Intent-driven: Agents express goals, not clicks
  • Tokenized payments: Secure delegation via SPT

Protocol Flow

A complete ACP transaction follows this flow:

  1. Discovery: Buyer agent fetches the merchant'smanifest.json to understand capabilities
  2. Search: Semantic search for products matching buyer intent
  3. Quote: Request a price quote, potentially with an initial offer
  4. Negotiate: Multi-turn negotiation until agreement or rejection
  5. Checkout: Initialize checkout session with agreed terms
  6. Finalize: Execute payment via Shared Payment Token

Discovery

Every ACP-compliant merchant exposes a manifest at /.well-known/acp/manifest.json:

json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "acp_version": "1.0",
  "merchant": {
    "id": "merchant_xyz",
    "name": "Acme Sports",
    "capabilities": ["negotiate", "bundle", "subscribe"]
  },
  "endpoints": {
    "search": "/acp/search",
    "quote": "/acp/quote",
    "checkout": "/acp/checkout/init",
    "finalize": "/acp/checkout/finalize"
  },
  "payment_methods": ["stripe_spt", "paypal_ba"],
  "supported_currencies": ["USD", "EUR", "GBP"],
  "policies": {
    "negotiation_enabled": true,
    "max_discount_percent": 20,
    "return_window_days": 30
  }
}

The manifest tells buyer agents what the merchant supports: negotiation capabilities, payment methods, currencies, and policy constraints.

Negotiation

Semantic Search

Unlike traditional keyword search, ACP uses semantic queries that express intent:

http
1
2
3
4
5
6
7
8
9
10
11
12
13
POST /acp/search HTTP/1.1
Host: acme-sports.agents.hyperfold.io
Content-Type: application/json
 
{
  "query": "waterproof running shoes for marathon",
  "filters": {
    "price_max": 200,
    "size": "10",
    "color_preference": ["blue", "black"]
  },
  "limit": 5
}

Response with semantically matched products:

json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "results": [
    {
      "product_id": "prod_aero_x2",
      "name": "AeroRun X2 Waterproof",
      "description": "Professional marathon shoe with Gore-Tex lining",
      "list_price": 180.00,
      "negotiable": true,
      "semantics": {
        "category": "apparel/footwear",
        "usage_context": ["marathon", "wet_conditions"],
        "visual_tags": ["blue", "reflective", "mesh_upper"]
      },
      "availability": {
        "in_stock": true,
        "quantity": 45,
        "shipping_estimate": "2-3 days"
      }
    }
  ],
  "total_count": 12,
  "semantic_confidence": 0.94
}

Price Negotiation

Buyer agents can make offers. The seller agent responds with accept, counter, or reject:

http
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /acp/quote HTTP/1.1
Host: acme-sports.agents.hyperfold.io
Content-Type: application/json
 
{
  "session_id": "sess_abc123",
  "product_id": "prod_aero_x2",
  "quantity": 1,
  "offer_price": 150.00,
  "buyer_context": {
    "loyalty_tier": "gold",
    "purchase_history": 12,
    "urgency": "flexible"
  }
}

Counter-offer response with bundle suggestion:

json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "status": "counter_offer",
  "original_price": 180.00,
  "counter_price": 162.00,
  "discount_applied": "10%",
  "reasoning": "Gold member discount applied. Best available price.",
  "valid_until": "2025-12-20T12:00:00Z",
  "bundle_suggestion": {
    "product_id": "prod_socks_wp",
    "name": "Waterproof Running Socks",
    "bundle_price": 25.00,
    "bundle_total": 179.00,
    "savings": 26.00
  }
}
Negotiation responses are time-limited. The valid_until timestamp indicates when the offer expires.

Checkout

Once terms are agreed, the buyer agent finalizes the purchase:

http
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /acp/checkout/finalize HTTP/1.1
Host: acme-sports.agents.hyperfold.io
Content-Type: application/json
 
{
  "session_id": "sess_abc123",
  "quote_id": "quote_xyz789",
  "accepted_price": 162.00,
  "payment_token": "spt_live_abc123...",
  "shipping_address": {
    "name": "John Doe",
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}

The payment_token is a Stripe Shared Payment Token (SPT) that allows the merchant to charge the buyer's payment method without exposing card details.

ACP Manifest Fields

FieldTypeDescription
acp_versionstringProtocol version (currently "1.0")
merchant.capabilitiesarraySupported features: negotiate, bundle, subscribe
endpointsobjectURL paths for search, quote, checkout operations
payment_methodsarrayAccepted payment types (stripe_spt, paypal_ba)
policies.max_discount_percentnumberMaximum negotiable discount percentage
Learn how Hyperfold implements ACP in the ACP API Reference.