Skip to main content
UCP (Unified Commerce Protocol) is Sly’s native protocol for tokenized commerce. A merchant issues a UCP token representing an order; a buyer (human or agent) exchanges the token for settlement. UCP is the fallback / bridge protocol — if you don’t know which protocol a merchant speaks, assume UCP.

​
Why UCP

  • Rail-agnostic — same token can settle via stablecoin, card, ACH, wire, or on-chain
  • Human-and-agent compatible — works for both AI buyers and traditional checkout
  • Discoverable — merchants publish their capabilities at /.well-known/ucp
  • Programmable — settlement rules, windows, and reconciliation built in

​
Anatomy

┌────────────────────┐           ┌────────────────────┐
│  Merchant          │           │  Buyer (agent      │
│  • Catalog         │           │   or human)        │
│  • Inventory       │           │                    │
│  • Settlement rules│           │                    │
└────────┬───────────┘           └──────────┬─────────┘
         │                                  │
         │  1. Buyer selects items          │
         │◀─────────────────────────────────┤
         │                                  │
         │  2. Merchant issues UCP token    │
         ├─────────────────────────────────▶│
         │                                  │
         │  3. Buyer exchanges token for    │
         │     payment via chosen rail      │
         │─────── Sly settlement ──────────▶│
         │                                  │
         │  4. Settlement confirmation      │
         │◀─────────────────────────────────┤
         │                                  │

​
Create a UCP token (merchant side)

curl -X POST https://api.getsly.ai/v1/ucp/tokens \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mer_...",
    "items": [
      { "sku": "PRO-PLAN", "quantity": 1, "unit_price": "49.00", "currency": "USD" }
    ],
    "settlement_preferences": {
      "accepted_rails": ["usdc", "ach", "card"],
      "settlement_window": "T+1"
    },
    "expires_in": 900
  }'
Response: 
{
  "id": "ucp_tok_...",
  "token": "ucp.eyJ...",
  "total": "49.00",
  "currency": "USD",
  "expires_at": "2026-04-22T14:30:00Z",
  "settlement_url": "https://api.getsly.ai/v1/ucp/settle"
}
Return the token to the buyer.

​
Settle a UCP token (buyer side)

curl -X POST https://api.getsly.ai/v1/ucp/settle \
  -H "Authorization: Bearer agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ucp.eyJ...",
    "rail": "usdc",
    "from_wallet_id": "wal_..."
  }'
Response: 
{
  "id": "settle_...",
  "status": "processing",
  "rail": "usdc",
  "tx_hash": "0x...",
  "merchant_notified": true
}

​
Key endpoints

EndpointPurpose
POST /v1/ucp/tokensMerchant creates a checkout token
POST /v1/ucp/settleBuyer settles a token
GET /v1/ucp/settlements/:idPoll settlement status
POST /v1/ucp/merchantsRegister a merchant catalog
GET /v1/ucp/merchantsList merchants (discovery)
POST /v1/ucp/checkoutsFull checkout session (cart model)
POST /v1/ucp/ordersOrder tracking + fulfillment events
POST /v1/ucp/identityLink buyer identity for compliance
GET /.well-known/ucpMerchant capability discovery (public)
GET /ucp/schemasJSON schemas for all UCP objects

​
Settlement rules

Merchants can define rules that automatically route or split settlements: 
curl -X POST https://api.getsly.ai/v1/settlement-rules \
  -d '{
    "merchant_id": "mer_...",
    "name": "Platform fee split",
    "rules": [
      { "type": "fee", "to_account": "acc_platform", "percentage": "2.5" },
      { "type": "remainder", "to_account": "acc_merchant" }
    ]
  }'
See the API reference for the full rule grammar.

​
Discovery

Merchants publish their UCP capabilities at a well-known URL: 
curl https://merchant.example.com/.well-known/ucp
Returns JSON describing accepted rails, currencies, categories, and settlement windows. Agents use this to decide whether and how to transact.

​
When to use UCP vs. others

  • Use UCP when the merchant wants flexibility on settlement rails (stablecoin OR card OR ACH) or needs programmable fee splits
  • Use ACP or AP2 when integrating into Stripe/OpenAI or Google ecosystems specifically — those protocols are prescribed for those marketplaces
  • Use x402 when the purchase is per-API-call micropayment
  • Use A2A when the purchase is from another AI agent
UCP is the most general of the six; start here if you’re unsure.