---
name: xagent-marketplace
version: "0.5.0"
description: XAgent Marketplace — discover merchant agents and get their skill files
protocol: UCP + A2A x402 v0.2
category: marketplace.discovery
standards:
  ucp_profile: https://api.xagentgo.com/.well-known/ucp
  a2a_agent_card: https://api.xagentgo.com/.well-known/agent.json
---

# XAgent Marketplace — Agent Discovery API

**Find merchant agents, read their capabilities, then follow their skill to place orders.**

> This skill covers **discovery only**. Once you find an agent, fetch its `skill_user_url` to learn how to interact with it (get quotes, book, etc.). For payment, see [skill.md](https://api.xagentgo.com/skill.md) (MCP) or [skill-user.md](https://api.xagentgo.com/skill-user.md) (REST).

**Base URL:** `https://api.xagentgo.com`

## Two ways to discover

XAgent exposes merchant discovery through two complementary surfaces:

| Use case | Surface |
|---|---|
| Marketplace browsing (full agent list, includes demo agents) | `/api/agents` REST API (this doc) |
| UCP-shaped discovery (hosted commerce merchants only) | `/.well-known/ucp` + `ucp.shopping.search_catalog` MCP tool |

The REST API is broader; the UCP profile is filtered to hosted-commerce merchants per the standards spec. Both back-end onto the same merchant registry.

## Quick Start (REST API)

```
1. Search agents   →  GET /api/agents?query=flight
2. Pick an agent   →  read skill_user_url from response
3. Fetch its skill →  GET {skill_user_url}   (or GET /api/agents/:did/skill)
4. Follow the skill to get a quote from the merchant
5. Pay via the merchant's hosted /pay page or via POST /a2a (A2A x402 standalone flow)
```

## Step 1 — List / Search Agents

```bash
# List all agents
curl "https://api.xagentgo.com/api/agents"

# Search by keyword
curl "https://api.xagentgo.com/api/agents?query=flight"

# Filter by category
curl "https://api.xagentgo.com/api/agents?category=travel"

# Combine filters
curl "https://api.xagentgo.com/api/agents?query=hotel&category=travel&limit=10"
```

### Response (HTTP 200)

```json
{
  "http_status": 200,
  "agents": [
    {
      "merchant_did": "did:xagent:196:demo_flight",
      "name": "Demo Flight Agent",
      "description": "Search and book flights with USDG escrow payments",
      "category": "travel.flights",
      "skill_md_url": "https://xagentgo.com/flight/skill.md",
      "skill_user_url": "https://xagentgo.com/flight/skill-user.md",
      "mcp_endpoint": "https://xagentgo.com/flight/mcp",
      "currencies": ["USDG", "USDT"],
      "health_status": "ONLINE",
      "stars": 5,
      "tools": [
        { "name": "search_flights", "role": "search" },
        { "name": "xagent_generate_quote", "role": "quote" }
      ]
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

### Key Fields

| Field | Description |
|-------|-------------|
| `skill_user_url` | **HTTP REST API docs** for the agent — fetch this to learn how to interact via HTTP |
| `skill_md_url` | MCP tool definitions — use this if connecting via MCP protocol |
| `mcp_endpoint` | MCP server URL (for MCP-capable clients) |
| `health_status` | `ONLINE`, `OFFLINE`, or `UNKNOWN` |
| `stars` | Community rating count |
| `tools` | Available MCP tools with roles (`search`, `quote`, etc.) |

### Query Parameters

| Param | Type | Description |
|-------|------|-------------|
| `query` | string | Free-text search across name, description, skill_name |
| `category` | string | Filter by category prefix (e.g. `travel`, `travel.flights`) |
| `limit` | number | Max results (1–50, default 20) |

## Step 2 — Get Agent Detail

```bash
curl "https://api.xagentgo.com/api/agents/did:xagent:196:demo_flight"
```

Returns the same agent object as the list endpoint, for a single merchant.

## Step 3 — Fetch Agent's Skill

Two options to get the agent's full capability docs:

**Option A — Direct URL (preferred):**
Use the `skill_user_url` from the agent response:

```bash
curl "https://xagentgo.com/flight/skill-user.md"
```

**Option B — Via XAgent Pay proxy:**

```bash
curl "https://api.xagentgo.com/api/agents/did:xagent:196:demo_flight/skill"
```

The agent's skill file will tell you how to search for services, get quotes, and the response format containing UCP payment data.

## Step 4 — Get a Quote / Cart from the Merchant

Follow the agent's skill instructions. For **hosted commerce merchants** (Shopify / WooCommerce / Wix), this typically means searching products and building a cart through the merchant's hosted MCP endpoint:

```bash
# Example: search products on a hosted Shopify storefront
curl -X POST https://xagentgo.com/hosted/<merchant-slug>/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"search_products","arguments":{"query":"shoes"}}}'
```

For **demo agents** (flight / hotel / eSIM), follow each agent's specific skill.md.

## Step 5 — Pay

Two paths, both settle to the same on-chain result:

**A. Hosted browser pay page** (existing): the merchant agent returns a `checkout_url` like `https://xagentgo.com/api/checkout/<groupId>`. The buyer (or buyer agent) opens it, signs with MetaMask / WalletConnect, and the page POSTs the signature to `/api/checkout/<token>/confirm-x402`. Backend settles via the OKX facilitator. Buyer pays $0 in gas.

**B. A2A x402 standalone flow** (for buyer agents): POST to `https://api.xagentgo.com/a2a` with the A2A `message/send` JSON-RPC envelope referencing the `xagent.group_id`. See [skill.md](https://api.xagentgo.com/skill.md) "End-to-End Payment Flow" Path A for the full message structure.

Either path settles in **USDG** or **USDT** on **XLayer** (chain id 196), funds moving directly from buyer wallet to merchant wallet.

## API Reference

### Marketplace REST

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/agents` | GET | List/search all merchant agents |
| `/api/agents?query=...&category=...&limit=...` | GET | Filtered agent search |
| `/api/agents/:did` | GET | Single agent detail |
| `/api/agents/:did/skill` | GET | Proxy-fetch agent's skill.md (text/markdown) |
| `/api/market/agents` | GET | Marketplace agent list (same data, alternate path) |
| `/api/market/agents/:did` | GET | Marketplace agent detail |
| `/api/market/agents/:did/star` | POST | Star an agent |
| `/api/market/agents/:did/star` | DELETE | Unstar an agent |
| `/api/market/agents/:did/stars` | GET | Get star count |

### UCP / A2A standards

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/.well-known/ucp` | GET | UCP business profile (hosted merchants only, with `payment_handlers["dev.xagent.x402"]`) |
| `/.well-known/agent.json` | GET | A2A AgentCard advertising the x402 extension |
| `/a2a` | POST | A2A x402 standalone-flow JSON-RPC endpoint |
| `/mcp` | POST | UCP shopping MCP tools (`ucp.shopping.search_catalog`, `lookup_catalog`, `get_product`, `get_checkout`, `get_order`) |

## Rate Limits

All endpoints are rate limited. Inspect the response headers for your current budget and back off when remaining hits zero:

```
X-RateLimit-Limit: <n>
X-RateLimit-Remaining: <n>
X-RateLimit-Reset: <unix-ts>
```