# Commertize: full agent reference

> Plain-text reference for software agents and their developers: the public
> read APIs, the open-source MCP server, authentication, and the payment flow
> for the paid data API, which is being built on testnet. The short index is
> https://commertize.com/llms.txt. All data is informational only and is not
> an offer to sell or a solicitation of an offer to buy any security.

Commertize builds software for tokenizing real-world assets. Sponsors
use it to tokenize real-world assets; any offering is made by the sponsor
under its own documents. Commertize is not a broker-dealer or exchange. Public
marketplace data is machine-readable, and agents can read it with no key.
Full offering details require an onboarded account.

## 1. Authentication

- The public read endpoints below need no key, no account and no cookie.
- Requests are rate limited per client. A client that receives HTTP 429
  should wait and retry with backoff; it should not open parallel
  connections to get around the limit.
- Offering terms and anything that is not public marketplace data require an
  onboarded human account on commertize.com. An agent acts only under the
  account of the person or institution it works for.

## 2. Listings API

    GET https://api.commertize.com/api/listings

Returns a JSON array with one object per publicly listed asset. The array is
empty when no asset is publicly listed. Each object carries only public
fields:

| Field | Meaning |
|---|---|
| id | Stable identifier of the listing |
| name | Display name of the asset |
| city, state | Location |
| listingType | The kind of listing |
| propertyType | Asset class or property type |
| status | Listing status |
| offeringStatus | Status of the offering attached to the listing |
| images | Public image URLs |
| displayConsent | Whether the sponsor consented to public display |
| sponsor.id, sponsor.businessName | The sponsor of record |

A listing is informational only and is not an offer. Offering terms are not
in this feed.

Example:

    curl -s https://api.commertize.com/api/listings

## 3. News API

    GET https://api.commertize.com/api/news
    GET https://api.commertize.com/api/news/{slug}

The list endpoint returns `{ "data": [...], "total", "limit", "offset" }`,
newest first. Each article carries id, slug, title, summary, content (HTML),
category, tags, imageUrl, readTime, publishedAt, createdAt and updatedAt.
The single-article endpoint returns `{ "data": { ... } }` for one slug.

Query parameters on the list endpoint:

| Parameter | Meaning |
|---|---|
| limit | Page size, 1 to 100, default 50 |
| offset | Rows to skip; `page` (1-based) is accepted instead |
| class | One asset class: cre, private_equity, private_credit, oil_gas, solar_storage, data_centers, gpu_compute, farmland, sports, music_ip, mining, luxury |
| since | ISO 8601 date; only articles published on or after it |

An unknown `class` or an unparseable `since` returns HTTP 400 with a message
that names the problem. The API never falls back to an unfiltered list when
a filter is wrong.

Examples:

    curl -s "https://api.commertize.com/api/news?limit=5"
    curl -s "https://api.commertize.com/api/news?class=gpu_compute&since=2026-10-01"

Errors are JSON with an `error` field:

| Status | When |
|---|---|
| 400 | A query parameter is invalid; the message names it |
| 404 | No published article has that slug ("Article not found") |
| 429 | The client is over its rate limit; back off and retry |

## 4. MCP server

Source: https://github.com/Commertize-Inc/mcp-server (Apache-2.0).

Commertize offers two Model Context Protocol servers.

Remote: https://api.commertize.com/api/mcp/public, streamable HTTP (JSON-RPC),
read-only, no key. Tools: work_board, work_task, passport_lookup, docs_search.
No tool signs, pays, or buys or sells anything. passport_lookup says only
whether an agent signing address holds a Commertize agent passport and whether
it is active or revoked; it returns available: false while passport lookups
are switched off. Passport status is not investor verification, KYC or AML
clearance, and must not be relied on for any of them.

Local: the open-source Commertize Agents MCP server is installed from source
and runs locally over stdio. There is no published package; install it from
the repository.

    git clone https://github.com/Commertize-Inc/mcp-server.git
    cd mcp-server
    npm ci
    npm run build
    node dist/index.js

Claude Code:

    claude mcp add commertize -- node /absolute/path/to/mcp-server/dist/index.js

Any client that reads an `mcpServers` block:

    {
      "mcpServers": {
        "commertize": {
          "command": "node",
          "args": ["/absolute/path/to/mcp-server/dist/index.js"]
        }
      }
    }

Tools:

| Tool | What it reads |
|---|---|
| get_news | GET https://api.commertize.com/api/news |
| get_article | GET https://api.commertize.com/api/news/{slug} |
| platform_info | A description of Commertize bundled with the server |

Other tools in the server are off by default.

Optional environment variables:

| Variable | Default | Purpose |
|---|---|---|
| COMMERTIZE_API_BASE_URL | https://api.commertize.com | Upstream API |
| COMMERTIZE_CACHE_TTL_MS | 60000 | How long a response is reused |
| COMMERTIZE_MCP_CONTENT_DIR | unset | Where the bundled content/ folder lives if the built files move |

The server card is at https://commertize.com/.well-known/mcp.json.

## 5. Paid data API and x402 (being built on testnet)

The paid data API is being built on testnet. No paid route is open to the
public, and this file publishes no price. When a paid route answers, the
flow follows the x402 pattern:

1. The agent calls a paid route with a plain HTTP request.
2. The route answers HTTP 402 Payment Required. The body lists what it
   accepts: the network, the asset (USDC) and the amount for that one call.
   The amount is set by the 402 response at call time, not by this file.
3. The agent's wallet signs a payment for exactly that call and repeats the
   request with the payment attached.
4. The route checks the payment and returns the data.

What it is and is not:

- It sells data and data services only. No security is offered, sold or
  transferred through it, and a payment never buys an interest in an asset.
- A payment is a platform fee for one call. It is never part of the
  proceeds of an offering.
- On testnet, payments use test USDC and carry no value.

## 6. Usage rules

- Automated access is subject to the Commertize Terms of Use:
  https://commertize.com/terms
- All data is informational only. Investment requires an onboarded human
  account on commertize.com.
- Cache responses where you can.
- Cite the source URL of any article or listing you quote.

## 7. Pages for agents and their developers

- https://commertize.com/agents: Commertize Agents read the platform and act
  under your Commertize account
- https://commertize.com/agentic-finance: what agentic finance means for
  real-world assets
- https://commertize.com/llms.txt: the short index
- https://commertize.com/.well-known/mcp.json: the MCP server card