> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # OpenClaw Service x402 Endpoint > Turn an OpenClaw service into a monetizable x402 endpoint with Alephant 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: ```text 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](https://www.loom.com/share/1a509da77eaf40fb87ac6e6f319cd128) ![OpenClaw Service x402 Endpoint architecture](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/67c061306693a171db3962142dec232f7ab56ac715ddc1571150a7c8d393201e/docs/assets/openclaw/openclaw-x402-architecture.svg) ## 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: | Setting | Recommended value | Why it matters | | -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | | HTTP Method | `POST` | Paid tool calls usually send structured JSON input. | | Path | A stable path, for example `/v1/news/report` | This is the target path Alephant forwards requests to after payment checks pass. | | Authentication | Gateway-origin verification or private network access | Buyers should not call OpenClaw directly; Alephant should remain the payment and policy gate. | | Request Content-Type | `application/json` | Keeps the endpoint easy for clients and agents to call. | | Response Format | One stable JSON object | Alephant, agents, and client applications can parse the result predictably. | | Timeout | An explicit service timeout | News collection and AI formatting can be slower than a simple database lookup. | | Concurrency | A configured service limit | Prevents paid traffic from overloading the upstream OpenClaw worker. | 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: ```json { "preset": "ai", "limit": 3, "deep_fetch": false } ``` Field descriptions: | Field | Type | Default | Description | | ------------ | ------- | ------- | --------------------------------------------------------------------------------------------- | | `preset` | string | `ai` | Selects the news report preset when the service supports multiple report modes. | | `limit` | integer | `3` | Maximum number of news items to include. Keep the range small enough for predictable latency. | | `deep_fetch` | boolean | `false` | Enables deeper upstream fetching when the buyer wants a richer report. | Example success response: ```json { "status": "ok", "tool": "ai_news_report", "format": "markdown", "content": "# AI News Report\n\n## 1. Market headline..." } ``` Example error response: ```json { "status": "error", "code": "UPSTREAM_TIMEOUT", "message": "The news report timed out before completion." } ``` 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. ![Create an Alephant Agent for an OpenClaw runtime](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/418899689e12e92ddb4a4ca650220d42a2454a83dd9971e5acd918bc3b78157b/docs/assets/openclaw/alephant-create-workflow-agent.jpg) Use a name and description that describe the paid capability, not the internal implementation. For example: | Field | Example | | ------------------ | ------------------------------------------------------------------- | | Agent Type | `AI Agent` | | Runtime Connection | `Custom Webhook` | | Agent Name | `News Report Service` | | Description | `Fetches real AI/tech news and returns an English Markdown report.` | | Environment | `Production` | 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. ![Create a new Agent Paid Endpoint basic info](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/37b7b641fb9fffe85c897f9eaa6f1f5cb431bdf8597c85fcd26efd53986252a6/docs/assets/openclaw/alephant-create-paid-endpoint-basic-info.jpg) Configure the basic endpoint fields first: | Field | Example | Notes | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Endpoint Type | `Agent Endpoint` | The endpoint invokes a linked Alephant Agent. | | Linked Agent | `News Report Service` | Select the Agent created in the previous step. | | Endpoint Name | `News Report Service` | This is what users see in the marketplace or endpoint list. | | Endpoint Slug | `news-report-service` | Alephant exposes it under `/x402/news-report-service`. | | Method | `POST` | Match the OpenClaw service method. | | Forwarding Target URL | `https://openclaw.example.com/v1/news/report` | The production OpenClaw endpoint. Do not expose local or private hostnames in public docs. | | Description | `Fetches real AI/tech news and returns an English Markdown report.` | Keep the user-facing description concrete and capability-focused. | 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. ![Configure paid endpoint schemas and examples](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/11ddcb399c3ebbf5e89aa2e279bb16c53ccb24cf782d327389fce52d23aad05a/docs/assets/openclaw/alephant-paid-endpoint-schema-examples.jpg) Example input schema: ```json { "type": "object", "required": ["preset", "limit", "deep_fetch"], "properties": { "preset": { "type": "string", "description": "News report preset to run.", "enum": ["ai"], "default": "ai", "examples": ["ai"] }, "limit": { "type": "integer", "description": "Maximum number of news items to include in the report.", "minimum": 1, "maximum": 10, "default": 3, "examples": [3] }, "deep_fetch": { "type": "boolean", "description": "When true, enables deeper retrieval before generating the report.", "default": false } } } ``` Example request: ```json { "preset": "ai", "limit": 3, "deep_fetch": false } ``` Example response: ```json { "status": "ok", "tool": "ai_news_report", "format": "markdown", "content": "# AI News Report\n\n..." } ``` 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. ```text 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. ![News Report Service listing in the Alephant marketplace](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/0e3ea9a086f8a9ff03d371b1cb28777659bee32b790c0fd4dcd230fdfbe2d426/docs/assets/openclaw/alephant-marketplace-finance-news-report.jpg) 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: ```bash 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`. ```bash curl -X POST "https://pay.alephant.io/x402/news-report-service" \ -H "Content-Type: application/json" \ -d '{"preset":"ai","limit":3,"deep_fetch":false}' ``` ![Unsigned x402 request returns payment-required](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/1f2f920dcaead04de3c96bdf5fdaf850119889e89c3f82dcf565da193810fee3/docs/assets/openclaw/alephant-x402-payment-required.jpg) Sign the payment requirements according to the x402 protocol, then send the request again with the signed payment payload: ```bash curl -X POST "https://pay.alephant.io/x402/news-report-service" \ -H "Content-Type: application/json" \ -H "PAYMENT-SIGNATURE: " \ -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](https://docs.cdp.coinbase.com/x402/welcome) * [How x402 Works](https://docs.cdp.coinbase.com/x402/core-concepts/how-it-works) * [Bazaar Quality Ranking](https://docs.cdp.coinbase.com/x402/bazaar#quality-ranking) * [Alephant Marketplace](https://alephant.io/marketplace) * [Paid Endpoints](/docs/overview/monetize/paid-endpoints)