Hermes Service x402 Endpoint

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:

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

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:

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:

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

Field descriptions:

Example success response:

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

Example error response:

1
{
2
  "status": "error",
3
  "code": "UPSTREAM_TIMEOUT",
4
  "message": "The finance 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 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.

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

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.

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

Example input schema:

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

Example request:

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

Example response:

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

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.

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

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

$
curl -X POST "https://pay.alephant.io/x402/finance-news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -d '{"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/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
• How x402 Works
• Bazaar Quality Ranking
• Alephant Marketplace
• Paid Endpoints