Run

POST /v1/run/{provider}/{endpoint} runs one tool with its input as the JSON body. Paid per call over x402; settled only on success.

POST /v1/run/{provider}/{endpoint}
content-type: application/json

The body is the tool's input, exactly as its input schema describes (inspect returns it). There is no wrapper object.

# returns 402 until paid
curl -si -X POST https://api.useakashi.xyz/v1/run/openweather/current \
  -H 'content-type: application/json' -d '{"city": "Lagos"}'

Payment flow

Step	Request	Response
1	The input, no payment header	`402` with `PAYMENT-REQUIRED`: x402 v2, scheme `exact`, network `eip155:84532`, asset USDC (`0x036CbD53842c5426634e7929541eC2318f3dCF7e`), the exact `amount` and `payTo` `0x8164dabAfc824322221654ED421715FdaA66948D`
2	The same request with `PAYMENT-SIGNATURE`	The gateway verifies the signature, then runs the tool
3		`200`: the run envelope, and `PAYMENT-RESPONSE` with the settlement on Base Sepolia
3		Any other status: an error or a not-found envelope. The payment is not settled.

Use an x402 client for steps 1 and 2: @x402/fetch (From code (HTTP)), the CLI or the MCP server.

The gateway checks the input after it verifies the payment. A run with a bad input costs nothing, but it still takes a signature: inspect first.

Responses

Status	Body	Charged
`200`	The run envelope, `found: true`	yes
`402`	`{}`; the price is in `PAYMENT-REQUIRED`	no
`404`	The run envelope with `found: false` (the thing does not exist), or an `unknown_endpoint` error	no
`400`, `413`, `422`	An error: `invalid_json`, `payload_too_large`, `invalid_input`	no
`429`, `502`, `503`, `504`	An error: `provider_rate_limited`, `provider_error`, `output_contract`, `relay_failed`, `tool_unavailable`, `deadline_exceeded`	no

An id that is not in the catalog answers 404 unknown_endpoint straight away, without a 402.

Response headers

Header	Value
`PAYMENT-RESPONSE`	On a settled run: base64 JSON with `success`, `transaction` (the Base Sepolia hash), `network` and `payer`
`X-Akashi-Via`	`pocket` when the run went through a Pocket relay, `direct` when the gateway called the backend itself
`X-Akashi-Endpoint`	The tool id that ran, e.g. `openweather/current`

Example

node akashi.mjs run wikipedia/summary --input '{"title": "Alan Turing"}'

The body of that run:

{
  "service": "tool-router",
  "endpoint": "wikipedia/summary",
  "provider": "wikipedia",
  "status": "ok",
  "found": true,
  "billable": true,
  "cached": false,
  "as_of": "2026-10-07T12:07:17+00:00",
  "elapsed_ms": 1418,
  "price": { "usd": "0.001", "atomic": "1000", "tier": "local", "network": "eip155:84532" },
  "render": "page",
  "notes": [],
  "sources": [{ "name": "wikipedia", "status": "ok", "url": "https://en.wikipedia.org/api/rest_v1/page/summary/Alan_Turing", "licence": "CC BY-SA 4.0" }],
  "data": {
    "title": "Alan Turing",
    "description": "English computer scientist (1912–1954)",
    "markdown": "Alan Mathison Turing was an English mathematician and logician…",
    "url": "https://en.wikipedia.org/wiki/Alan_Turing",
    "wikidata_id": "Q7251",
    "lang": "en"
  }
}

Good practice

Inspect before the first run of a tool, and copy its example.
Split multi-source jobs into several small runs; run independent ones in parallel.
Retry only errors with retryable: true, after a pause.
Tell the user what a run cost when it matters (price.usd).

Payment flow

Responses

Response headers

Example

Good practice

On this page