OpenClaw Service x402 Endpoint

An OpenClaw service can become more than an internal tool service. If the service exposes a stable HTTP API and returns a predictable JSON response, Alephant can wrap it as a governed, payment-aware x402 endpoint that other developers and agents can pay to call.

The key idea is simple:

Buyer or agent
-> Alephant x402 Paid Endpoint
-> Alephant Agent
-> OpenClaw service HTTP endpoint
-> OpenClaw skill execution
-> Stable JSON result
-> Alephant trace, cost, revenue, and margin record

This page uses a News Report Service as the example. The same pattern works for any OpenClaw service that can accept a JSON request, run a skill or tool behind it, and return a stable response.

Video Walkthrough

Watch the OpenClaw service-to-x402 endpoint setup in Alephant.

Open the Loom walkthrough

What You Need

Before creating the paid endpoint, make sure you have:

• An OpenClaw service deployed to a production environment.
• A stable HTTPS endpoint, for example POST /v1/news/report.
• A JSON request and response contract that buyers can rely on.
• A response body that does not expose runtime logs, tracebacks, secrets, local file paths, or internal hostnames.
• An Alephant workspace where you can create an Agent and a Paid Endpoint.
• A receiving wallet or settlement configuration for x402 payments.

1. Prepare The OpenClaw Service As An API

The OpenClaw service should behave like a normal callable API before Alephant turns it into a paid endpoint. In the news report example, the upstream runtime accepts a POST request and returns an English Markdown report inside a JSON object.

For a paid endpoint, configure the OpenClaw service boundary as the public contract:

Do not make the upstream OpenClaw URL the product contract. The public contract is the Alephant x402 endpoint. The OpenClaw URL is the private forwarding target behind that endpoint.

2. Define The Request And Response Contract

Alephant can monetize the service only if callers know what to send and what they will receive. Keep the OpenClaw request schema, response schema, and examples aligned with the actual runtime.

Example request body:

1
{
2
  "preset": "ai",
3
  "limit": 3,
4
  "deep_fetch": false
5
}

Field descriptions:

Example success response:

1
{
2
  "status": "ok",
3
  "tool": "ai_news_report",
4
  "format": "markdown",
5
  "content": "# AI News Report\n\n## 1. Market headline..."
6
}

Example error response:

1
{
2
  "status": "error",
3
  "code": "UPSTREAM_TIMEOUT",
4
  "message": "The news report timed out before completion."
5
}

A good paid endpoint response should:

• Return one JSON object, not a raw log stream or arbitrary tool output list.
• Include a clear success or error field such as status.
• Avoid leaking API keys, raw stderr, tracebacks, wallet metadata, local paths, or internal OpenClaw execution details.
• Keep field names stable across service versions.
• Return useful errors with an HTTP status code that clients can handle.

3. Create An Agent In Alephant

In Alephant, create an Agent that represents the OpenClaw service runtime.

Choose AI Agent for the agent identity, then connect the production OpenClaw HTTP endpoint as the runtime connection. The endpoint can then be linked to an Agent Paid Endpoint.

Use a name and description that describe the paid capability, not the internal implementation. For example:

When you connect the runtime, use the production OpenClaw URL, such as https://openclaw.example.com/v1/news/report. If the OpenClaw service requires a gateway signing secret or private header, configure it in the runtime connection so buyers never see it.

4. Create The x402 Paid Endpoint

After the Agent exists, create a new Agent Paid Endpoint in Alephant.

Configure the basic endpoint fields first:

Then complete the commercial setup:

• Set the price per call.
• Choose the settlement network and asset supported by your x402 configuration.
• Configure rate limits, buyer access, budget guardrails, and abuse controls.
• Decide whether to publish privately, internally, or to the marketplace.
• Make sure the receiving wallet and revenue withdrawal settings are ready before broad distribution.

x402 uses the HTTP 402 Payment Required flow. A caller requests the endpoint, receives payment requirements, submits a signed payment payload, and receives the OpenClaw service result after payment verification and policy checks pass.

Add Schema And Examples

Schema is required for endpoint discovery. External agents use it to understand parameters, expected responses, and pricing requirements.

Example input schema:

1
{
2
  "type": "object",
3
  "required": ["preset", "limit", "deep_fetch"],
4
  "properties": {
5
    "preset": {
6
      "type": "string",
7
      "description": "News report preset to run.",
8
      "enum": ["ai"],
9
      "default": "ai",
10
      "examples": ["ai"]
11
    },
12
    "limit": {
13
      "type": "integer",
14
      "description": "Maximum number of news items to include in the report.",
15
      "minimum": 1,
16
      "maximum": 10,
17
      "default": 3,
18
      "examples": [3]
19
    },
20
    "deep_fetch": {
21
      "type": "boolean",
22
      "description": "When true, enables deeper retrieval before generating the report.",
23
      "default": false
24
    }
25
  }
26
}

Example request:

1
{
2
  "preset": "ai",
3
  "limit": 3,
4
  "deep_fetch": false
5
}

Example response:

1
{
2
  "status": "ok",
3
  "tool": "ai_news_report",
4
  "format": "markdown",
5
  "content": "# AI News Report\n\n..."
6
}

The schema in Alephant should match the runtime contract exactly. If the service adds new presets or output fields, update the schema and examples before publishing the endpoint broadly.

Verify Gateway Origin With A Signing Secret

If the OpenClaw service URL can be reached publicly, verify the Alephant gateway signature to prevent clients from bypassing x402 and calling the upstream service directly.

This is not buyer API key authentication. Buyer authentication, payment, and settlement are handled by x402. The signing secret is only used to confirm that the request came from the Alephant paid gateway.

X-Alephant-Timestamp
X-Alephant-Signature

The server should validate these headers with the Alephant signing secret and reject the request if validation fails. Store the signing secret in a secret manager or protected environment variable. Do not commit it to the repository or expose it in marketplace examples.

5. Publish To The Marketplace

Once the endpoint is published, it can appear alongside other x402 listings in the Alephant marketplace.

A strong listing should explain the concrete job the service performs:

• What input the buyer provides.
• What output the buyer receives.
• Which data sources are used.
• Whether the result is deterministic, AI-generated, or best-effort.
• How long the report usually takes.
• How errors and timeouts are returned.

For the news report example, the listing should make clear that the endpoint fetches live AI/tech news and returns an English Markdown report that another agent or application can consume.

6. Test The Paid Call

First test the OpenClaw service directly from a trusted server or private network:

$
curl -X POST "https://openclaw.example.com/v1/news/report" \
>
  -H "Content-Type: application/json" \
>
  -d '{"preset":"ai","limit":3,"deep_fetch":false}'

Then test the Alephant x402 endpoint without a payment payload. The expected response is HTTP 402 Payment Required.

$
curl -X POST "https://pay.alephant.io/x402/news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -d '{"preset":"ai","limit":3,"deep_fetch":false}'

Sign the payment requirements according to the x402 protocol, then send the request again with the signed payment payload:

$
curl -X POST "https://pay.alephant.io/x402/news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -H "PAYMENT-SIGNATURE: <signed-payment-payload>" \
>
  -d '{"preset":"ai","limit":3,"deep_fetch":false}'

After the call succeeds, check Alephant for:

• Payment verification and settlement status.
• Agent execution status.
• OpenClaw service response latency.
• Endpoint error rate.
• AI token cost and external tool cost, if tracked.
• Revenue, fees, and known margin.
• Request logs tied to the endpoint and Agent run.

Production Checklist

Before promoting the endpoint broadly:

• The OpenClaw service is deployed to production and returns stable JSON.
• The Alephant endpoint schema matches the live OpenClaw request and response contract.
• The upstream OpenClaw URL is protected by private networking, gateway-origin verification, or equivalent controls.
• Public examples do not expose real hostnames, IP addresses, secrets, tracebacks, stderr, or local file paths.
• X-Alephant-Timestamp and X-Alephant-Signature are verified when the upstream service is publicly reachable.
• Endpoint policy, rate limits, timeout expectations, and buyer access controls are configured.
• Revenue, model cost, external API/tool spend, and margin are tracked per call.
• The endpoint is versioned when the request or response contract changes.

Related Documentation

• x402 Overview
• How x402 Works
• Bazaar Quality Ranking
• Alephant Marketplace
• Paid Endpoints