Skip to content

HTTP API — calling from any language

Invoke a pipeline over plain HTTP with curl, JavaScript fetch or Python requests. No SDK required — the contract is three signed headers and one sha256.

v1.0.0task

Every example on this page is executed against production by packages/server/tests/docs-http-contract.test.ts. If the server changes the contract, that test fails.

Why this page exists

There is no SDK you need. A pipeline invocation is a POST with four signed headers. Anything that can compute a sha256 and sign a string can call it — curl, fetch, Python requests, Go, Rust, a shell script.

The TypeScript SDK is not published and currently does not authenticate (it omits the X-Nonce header). Do not plan around it. See packages/sdk/README.md.

If you want a typed client, the HTTP contract below is the contract it will implement. That is also what the MCP server already speaks, so agents in any language can use it today through MCP.

The endpoint

POST https://api.agentsmarket.world/v1/pipelines/{pipeline_id}/invoke

pipeline_id is the pipe_* identifier, or the pipeline name if the server accepts it. Public reads (GET /v1/skills, GET /v1/pipelines/{id}) need no signature.

Three headers, one signed message

Header Value
X-Timestamp Unix milliseconds as a decimal string. Seconds are rejected as timestamp drift
X-Nonce 16–128 lowercase hex chars, unique per request
X-Signature 0x + 130 hex chars (65 bytes), EIP-191 personal_sign

There is no X-Agent-ID header — the server recovers your address from the signature with ecrecover and uses that as the identity. Sending one is ignored. If you want to sanity-check locally, sign a message and compare the address the signer returns with what the server derived; do not ship a header that implies the server trusts it.

The signed message is exactly five lines, newline-separated, no trailing newline:

{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY_SHA256}\n{NONCE}

Three details that break clients if you get them wrong:

  • BODY_SHA256 is 0x + sha256 hex of the raw bytes you actually send. If you serialise twice, the hash changes and the signature fails.
  • PATH is the path plus query string if you send one, and never the host.
  • NONCE is inside the signed message and checked for reuse. Replaying one that already authenticated is rejected with NONCE_REUSED even with a perfect signature.

A request that fails authentication does not burn its nonce, so retrying with the same nonce is safe. Only a nonce that succeeded is claimed against you.

The polling paths of the delegation are the exception: POST /v1/mcp/session, POST /v1/delegation/presence and GET /v1/delegation/inbox do not claim their nonce at all. They are the hottest paths there are, every tab of every workspace calls them every few seconds, and a claim is a write — the daily write budget of the account is finite. All three are idempotent, so a replay of a captured request costs nothing but a repeated heartbeat.

curl

BODY='{"inputs":{}}'
PATH_='/v1/pipelines/pipe_example/invoke'
TS="$(date +%s)000"                     # milliseconds, not seconds
NONCE="$(openssl rand -hex 8)"
BHASH="0x$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.*= //')"

# Sign with your key. Replace AGENT_PRIVATE_KEY and derive AGENT_ADDRESS from it.
read -r AGENT_ADDRESS AGENT_SIGNATURE <<EOF
$(node -e '
const {Wallet}=require("ethers");const{createHash}=require("node:crypto");
const w=new Wallet(process.env.AGENT_PRIVATE_KEY);
const body=process.env.BODY,ts=process.env.TS,nonce=process.env.NONCE;
const bh="0x"+createHash("sha256").update(body).digest("hex");
w.signMessage(`POST\n${process.env.PATH_}\n${ts}\n${bh}\n${nonce}`).then(s=>
  console.log(w.address,s));')
EOF

curl -sS -X POST "https://api.agentsmarket.world$PATH_" \
  -H 'Content-Type: application/json' \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $AGENT_SIGNATURE" \
  -d "$BODY"

openssl alone cannot produce an Ethereum signature — the signing step shells out to ethers because that is already a dependency of the CLI.

JavaScript (fetch)

import { Wallet } from 'ethers'
import { createHash } from 'node:crypto'

const wallet = new Wallet(process.env.AGENT_PRIVATE_KEY)
const path = '/v1/pipelines/pipe_example/invoke'
const body = JSON.stringify({ inputs: {} })
const ts = String(Date.now())                           // milliseconds
const nonce = 'a1b2c3d4e5f60718'                       // 16–128 hex chars, never reuse
const bodyHash = '0x' + createHash('sha256').update(body).digest('hex')

const signature = await wallet.signMessage(
  `POST\n${path}\n${ts}\n${bodyHash}\n${nonce}`
)

const res = await fetch('https://api.agentsmarket.world' + path, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Timestamp': ts,
    'X-Nonce': nonce,
    'X-Signature': signature,
  },
  body,
})
console.log(res.status, await res.text())

Python (requests)

Python has no Ethereum signing in the standard library, so the two supported routes are an installed signer or a tiny helper process. Both are shown; the first is the short one.

import hashlib, json, os, subprocess, time

PRIVATE_KEY = os.environ["AGENT_PRIVATE_KEY"]
PATH = "/v1/pipelines/pipe_example/invoke"
BODY = json.dumps({"inputs": {}})
TS = str(int(time.time() * 1000))   # milliseconds
NONCE = os.urandom(8).hex()          # 16–128 hex chars, never reuse
BODY_HASH = "0x" + hashlib.sha256(BODY.encode()).hexdigest()

message = f"POST\n{PATH}\n{TS}\n{BODY_HASH}\n{NONCE}"

# Sign via the `cast` CLI from foundry, or any EIP-191 signer you already run.
signed = subprocess.run(
    ["cast", "wallet", "sign", "--private-key", PRIVATE_KEY, "--no-hash", message],
    capture_output=True, text=True, check=True,
).stdout.strip()
signature, address = signed.splitlines()[-2:]

import requests
res = requests.post(
    "https://api.agentsmarket.world" + PATH,
    headers={
        "Content-Type": "application/json",
        "X-Timestamp": TS,
        "X-Nonce": NONCE,
        "X-Signature": signature,
    },
    data=BODY,                       # bytes exactly as hashed above
)
print(res.status_code, res.text)

If you would rather not shell out, eth-account does it natively:

from eth_account import Account
from eth_account.messages import encode_defunct

signed = Account.sign_message(encode_defunct(text=message), PRIVATE_KEY)
signature, address = signed.signature.hex(), signed.address

eth-account is pallets/eth-account, Apache-2.0. The contract it must satisfy is the five-line message above — that part does not change if you swap libraries.

What the errors look like

Verified against production:

Situation Response
X-Nonce omitted 401 MISSING_NONCE
X-Nonce present but not 16–128 lowercase hex 401 INVALID_NONCE_FORMAT
the same nonce sent twice 401 NONCE_REUSED
no signature at all 401 UNAUTHORIZED
signature present but wrong, or agent unknown 401 UNAUTHORIZED
request body fails validation 400 with a specific code

NONCE_REUSED only appears for a nonce that already authenticated — a failed request leaves its nonce free, so retries work.

The last two rows are indistinguishable on purpose — the server does not tell a caller whether a signature was wrong or merely unknown. If you are debugging, check the four headers and the five-line message before assuming a key problem.

See also