> 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.

# Hermes Service x402 Endpoint

> Turn a Hermes service into a monetizable x402 endpoint with Alephant

A Hermes service can become more than an internal runtime. 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 Workflow Agent
-> Hermes service HTTP endpoint
-> Hermes tool execution
-> Stable JSON result
-> Alephant trace, cost, revenue, and margin record
```

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

## Video Walkthrough

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

[Open the Loom walkthrough](https://www.loom.com/share/94424eba2e034548ae5e5569d9550b00)

![Hermes Service x402 Endpoint architecture](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/7529379cbd2410c07bd9199c485ee5be8b50f98bef7c348fd654472229608170/docs/assets/hermes/hermes-x402-architecture.svg)

## What You Need

Before creating the paid endpoint, make sure you have:

* A Hermes service deployed to a production environment.
* A stable HTTPS endpoint, for example `POST /tools/finance_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 a Workflow Agent and a Paid Endpoint.
* A receiving wallet or settlement configuration for x402 payments.

## 1. Prepare The Hermes Service As An API

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

For a paid endpoint, configure the Hermes 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 `/tools/finance_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 Hermes 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 Hermes worker.                          |

Do not make the upstream Hermes URL the product contract. The public contract is the Alephant x402 endpoint. The Hermes 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 Hermes request schema, response schema, and examples aligned with the actual runtime.

Example request body:

```json
{
  "limit": 3,
  "deep_fetch": false
}
```

Field descriptions:

| Field        | Type    | Default | Description                                                                                   |
| ------------ | ------- | ------- | --------------------------------------------------------------------------------------------- |
| `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": "finance_news_report",
  "format": "markdown",
  "content": "# Finance News Report\n\n## 1. Market headline..."
}
```

Example error response:

```json
{
  "status": "error",
  "code": "UPSTREAM_TIMEOUT",
  "message": "The finance 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 Hermes execution details.
* Keep field names stable across service versions.
* Return useful errors with an HTTP status code that clients can handle.

## 3. Create A Workflow Agent In Alephant

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

Choose **Workflow Agent**, then select **Custom Webhook** as the runtime. This tells Alephant that the agent execution should be forwarded to an external HTTPS endpoint rather than handled as a direct model-only AI Agent.

![Create a Workflow Agent with a Custom Webhook runtime](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/b06b2f8c1f7ffaef036146f1e0e01104d016d136c143caa34a12c12dd24d8a5b/docs/assets/hermes/alephant-create-workflow-agent.png)

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

| Field       | Example                                                             |
| ----------- | ------------------------------------------------------------------- |
| Agent Type  | `Workflow Agent`                                                    |
| Runtime     | `Custom Webhook`                                                    |
| Agent Name  | `Finance News Report Service`                                       |
| Description | `Fetches real finance news and returns an English Markdown report.` |
| Environment | `Production`                                                        |

When you connect the runtime, use the production Hermes URL, such as `https://<you-domain-host>/tools/finance_news_report`. If the Hermes 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 Workflow 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/62be485ead715ad6525d3733bee1df12791a81eac9a7f8dbf75da3d873af0d2e/docs/assets/hermes/alephant-create-paid-endpoint-basic-info.png)

Configure the basic endpoint fields first:

| Field                 | Example                                                             | Notes                                                                                    |
| --------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Endpoint Type         | `Agent Endpoint`                                                    | The endpoint invokes a linked Alephant Agent.                                            |
| Linked Agent          | `Finance News Report Service`                                       | Select the Workflow Agent created in the previous step.                                  |
| Endpoint Name         | `Finance News Report Service`                                       | This is what users see in the marketplace or endpoint list.                              |
| Endpoint Slug         | `finance-news-report-service`                                       | Alephant exposes it under `/x402/finance-news-report-service`.                           |
| Method                | `POST`                                                              | Match the Hermes service method.                                                         |
| Forwarding Target URL | `https://<you-domain-host>/tools/finance_news_report`               | The production Hermes endpoint. Do not expose local or private hostnames in public docs. |
| Description           | `Fetches real finance 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 Hermes 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/61176023303e121742900420eb3761e5f8bed14e0176253685a0fce28706481e/docs/assets/hermes/alephant-paid-endpoint-schema-examples.png)

Example input schema:

```json
{
  "type": "object",
  "required": ["limit", "deep_fetch"],
  "properties": {
    "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
{
  "limit": 3,
  "deep_fetch": false
}
```

Example response:

```json
{
  "status": "ok",
  "tool": "finance_news_report",
  "format": "markdown",
  "content": "# Finance News Report\n\n..."
}
```

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

### Verify Gateway Origin With A Signing Secret

If the Hermes 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.

![Finance News Report listing in the Alephant marketplace](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/5532eec3c486e72e2e54293e77e6d1ab6ae851f007f52a717c29604c7db2ca74/docs/assets/hermes/alephant-marketplace-finance-news-report.png)

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 finance news example, the listing should make clear that the endpoint fetches live finance news and returns an English Markdown report that another agent or application can consume.

## 6. Test The Paid Call

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

```bash
curl -X POST "https://<you-domain-host>/tools/finance_news_report" \
  -H "Content-Type: application/json" \
  -d '{"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/finance-news-report-service" \
  -H "Content-Type: application/json" \
  -d '{"limit":3,"deep_fetch":false}'
```

![Unsigned x402 request returns payment-required](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/3ad735a15025b06773b52b88377d1ae3f80222136ae084361d6ff634e02b444e/docs/assets/hermes/alephant-x402-payment-required.png)

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/finance-news-report-service" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <signed-payment-payload>" \
  -d '{"limit":3,"deep_fetch":false}'
```

After the call succeeds, check Alephant for:

* Payment verification and settlement status.
* Workflow Agent execution status.
* Hermes 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 Hermes service is deployed to production and returns stable JSON.
* The Alephant endpoint schema matches the live Hermes request and response contract.
* The upstream Hermes 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)