---
name: xagent-core
version: "0.5.0"
description: XAgent Core — agentic-commerce gateway implementing UCP merchant discovery, A2A x402 standalone-flow payments, and MCP shopping tools on XLayer mainnet
protocol: UCP + A2A x402 v0.2 + Coinbase x402 + EIP-3009
category: commerce.gateway
currencies: [USDG, USDT]
chain_id: 196
payment_methods: [DIRECT_TRANSFER]
standards:
  ucp_profile: https://api.xagentgo.com/.well-known/ucp
  a2a_agent_card: https://api.xagentgo.com/.well-known/agent.json
  a2a_endpoint: https://api.xagentgo.com/a2a
  handler_schema: https://standards.xagentgo.com/dev-xagent-x402/v1.json
tools:
  - name: discover_agents
    role: discovery
    description: Search and discover merchant agents by keyword/category, ranked by stars
  - name: get_agent_skill
    role: discovery
    description: Fetch full skill.md content for a specific merchant agent
  - name: ucp.shopping.search_catalog
    role: ucp.catalog
    description: List hosted merchants as a UCP catalog (advertised storefronts)
  - name: ucp.shopping.lookup_catalog
    role: ucp.catalog
    description: Batch resolve hosted merchants by DID
  - name: ucp.shopping.get_product
    role: ucp.catalog
    description: Single hosted merchant detail
  - name: ucp.shopping.get_checkout
    role: ucp.checkout
    description: Retrieve a checkout group as UCP-shaped checkout entity
  - name: ucp.shopping.get_order
    role: ucp.order
    description: Retrieve a payment as a UCP-shaped order entity
---

# XAgent Core — MCP Skill

**XAgent is an agentic-commerce gateway**: AI buyer agents discover hosted online stores (Shopify / WooCommerce / Wix) and pay merchants directly on XLayer in regulated stablecoins. Settlement is non-custodial — funds move buyer wallet → merchant wallet on-chain. Buyers pay $0 in gas (the OKX OnchainOS x402 facilitator pays it).

> For non-MCP integration: see [skill-user.md](https://api.xagentgo.com/skill-user.md) (REST), [skill-market.md](https://api.xagentgo.com/skill-market.md) (marketplace discovery), or fetch the standards endpoints listed above.

## MCP Connection

```json
{
  "mcpServers": {
    "xagent-core": {
      "url": "https://api.xagentgo.com/mcp"
    }
  }
}
```

Transport: **Streamable HTTP** (stateless, single `POST /mcp` per request). Required header: `Accept: application/json, text/event-stream`.

## Standards endpoints

XAgent advertises itself via three standard discovery surfaces. Any compliant client can discover and pay our merchants without writing XAgent-specific code.

| Endpoint | Standard | Method |
|---|---|---|
| `https://api.xagentgo.com/.well-known/ucp` | UCP business profile | `GET` |
| `https://api.xagentgo.com/.well-known/agent.json` | A2A AgentCard advertising the x402 extension | `GET` |
| `https://api.xagentgo.com/a2a` | A2A x402 standalone-flow JSON-RPC | `POST` |
| `https://standards.xagentgo.com/dev-xagent-x402/v1.json` | `dev.xagent.x402` payment handler schema | `GET` |

For full A2A x402 wire format, see the [handler schema](https://standards.xagentgo.com/dev-xagent-x402.md).

## MCP Tools

XAgent Core exposes two namespaces of MCP tools at `/mcp`:

- **Marketplace discovery** (`discover_agents`, `get_agent_skill`)
- **UCP shopping** (`ucp.shopping.*`) — UCP-compliant catalog, checkout, and order tools. The read-only catalog and order methods are documented below; additional methods follow the same UCP namespace and return standard UCP responses.

### Marketplace discovery

#### `discover_agents`

Search and discover merchant agents in the marketplace. Returns agents ranked by stars.

| Param | Type | Required | Description |
|---|---|---|---|
| `query` | string | No | Keyword to search agent names and descriptions |
| `category` | string | No | Category prefix filter (e.g. `retail`, `travel`) |
| `limit` | number | No | Max results (default 20, max 50) |

#### `get_agent_skill`

Fetch the full skill.md content for a specific merchant agent.

| Param | Type | Required | Description |
|---|---|---|---|
| `merchant_did` | string | Yes | Merchant DID (e.g. `did:xagent:196:xstore`) |

---

### UCP shopping — fully wired (read-only)

These read-only methods accept an optional UCP `meta` object (`ucp-agent.profile`, `idempotency-key`) and return UCP-shaped responses with a `ucp` envelope. Only **hosted-commerce merchants** appear in catalog results — demo agents are deliberately not advertised.

#### `ucp.shopping.search_catalog`

Search the gateway's catalog of hosted merchant storefronts. Each storefront is modeled as a UCP product entry (id = merchant DID, title = store name).

| Param | Type | Required | Description |
|---|---|---|---|
| `meta` | object | No | UCP request meta block |
| `query` | string | No | Free-text search across merchant names and descriptions |
| `filters` | object | No | Structured filters (currently ignored) |
| `pagination` | object | No | `{ limit, offset }` |

#### `ucp.shopping.lookup_catalog`

Batch lookup of hosted merchants by DID.

| Param | Type | Required | Description |
|---|---|---|---|
| `meta` | object | No | UCP request meta block |
| `ids` | string[] | Yes | Merchant DIDs to resolve |
| `filters` | object | No | Structured filters |

#### `ucp.shopping.get_product`

Get a single hosted merchant by DID. Returns `product_not_found` for non-hosted merchants (preserving the hosted-only filter).

| Param | Type | Required | Description |
|---|---|---|---|
| `meta` | object | No | UCP request meta block |
| `id` | string | Yes | Merchant DID |
| `selected_options` | object | No | Reserved for future variant selection |

#### `ucp.shopping.get_checkout`

Retrieve the current state of a checkout (group) by id. Returns a UCP-shaped checkout with line items, totals, status, and a `permalink_url` to the browser checkout page.

| Param | Type | Required | Description |
|---|---|---|---|
| `meta` | object | No | UCP request meta block |
| `id` | string | Yes | Checkout / group id |

The response carries the UCP-standard checkout status (`pending`, `ready`, `submitted`, `completed`, `expired`).

#### `ucp.shopping.get_order`

Retrieve a single order (payment) by its order id. Returns a UCP-shaped order entity with line items, fulfillment status, totals, and the on-chain transaction hash.

| Param | Type | Required | Description |
|---|---|---|---|
| `meta` | object | No | UCP request meta block |
| `id` | string | Yes | order id of the order |

For live payments today, use the `/a2a` standalone flow or the hosted `/api/checkout/*` HTTP flow described below.

## End-to-End Payment Flow (today)

XAgent supports two complementary paths to settle a payment. Both reuse the same internal `PaymentRail` (XLayer x402 via OKX facilitator), so a payment driven through either path produces the same on-chain outcome and merchant webhook.

### Path A — A2A x402 standalone (recommended for buyer agents)

```
1. Buyer agent fetches  https://api.xagentgo.com/.well-known/agent.json
   to discover the x402 extension URI + handler schema URL.

2. Buyer agent obtains  xagent.group_id  (via existing /api/checkout flow,
   merchant skill quote, or a future create_checkout MCP tool).

3. POST /a2a  with metadata { "xagent.group_id": <id> }
   →  Task input-required + x402.payment.required = PaymentRequirements
      (scheme=exact, network=xlayer, payTo, asset, EIP-712 domain in extra)

4. Buyer signs the EIP-3009 TransferWithAuthorization locally.

5. POST /a2a  with metadata {
     "xagent.group_id": <id>,
     "x402.payment.payload": { x402Version: 1, scheme, network, payload: { signature, authorization } }
   }
   →  Task completed + x402.payment.receipts = [{ success, transaction, network, payer }]
```

Failed paths return Task `failed` with a structured `x402.payment.error` code (e.g. `INVALID_SIGNATURE`, `EXPIRED_PAYMENT`, `SETTLEMENT_FAILED`). See the [handler schema](https://standards.xagentgo.com/dev-xagent-x402/v1.json) for the full taxonomy.

### Path B — Browser HTTP 402 (existing, for hosted Shopify pay pages)

```
1. User lands on  https://xagentgo.com/api/checkout/:token  (hosted pay page).

2. Browser fetches  GET /api/checkout/:token  →  PaymentInstruction with
   eip3009.domain + eip3009.message ready to sign.

3. User signs via MetaMask / WalletConnect.

4. Browser POSTs the signature to  /api/checkout/:token/confirm-x402.

5. Backend settles via OKX facilitator → mark payments SETTLED → fire merchant webhook.
```

Both paths converge on the same settlement logic; status transitions are identical.

## Networks and tokens

| Network | Chain ID | Network identifier | Status |
|---|---|---|---|
| XLayer Mainnet | `196` | `xlayer` | ✅ Production |

| Token | Address | Decimals | EIP-712 `name` | EIP-712 `version` |
|---|---|---|---|---|
| **USDG** (preferred) | `0x4ae46a509f6b1d9056937ba4500cb143933d2dc8` | 6 | `Global Dollar` | `1` |
| **USDT** | `0x779ded0c9e1022225f8e0630b35a9b54be713736` | 6 | `USD₮0` | `1` |

> Use the literal EIP-712 `name` / `version` values in the table above when constructing the signing domain.

## Security

### EIP-3009 signing

All payments are settled via `transferWithAuthorization` with EIP-712 typed data. Buyers sign over the canonical domain (`name`, `version`, `chainId`, `verifyingContract`) plus the authorization (`from`, `to`, `value`, `validAfter`, `validBefore`, `nonce`). The 32-byte nonce prevents replay; `validBefore` enforces a time bound.

### Non-custodial

XAgent never holds funds. The OKX facilitator submits the signed `transferWithAuthorization` on-chain, moving tokens directly from buyer wallet to merchant wallet. XAgent only observes the resulting tx hash.

### Hosted-only public exposure

Only hosted-commerce merchants are advertised in `/.well-known/ucp`, `/.well-known/agent.json`, and `ucp.shopping.*` catalog results. Demo agents (flight / hotel / eSIM) and platform internals are not publicly discoverable.

## Settlement infrastructure

- **Facilitator**: OKX OnchainOS x402 facilitator. Gas is sponsored by the facilitator, so buyers need no native token.
- **Chain**: XLayer Mainnet (chainId 196), OKX zkEVM L2.
- **Explorer**: `https://www.okx.com/web3/explorer/xlayer` (verify any settlement by tx hash).

## Source

Public agent manifests, the `skill.md` spec, and integration examples: [github.com/rocloveai/xagent-skills](https://github.com/rocloveai/xagent-skills). Learn more at [xagentgo.com](https://xagentgo.com).