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.
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_SHA256is0x+ sha256 hex of the raw bytes you actually send. If you serialise twice, the hash changes and the signature fails.PATHis the path plus query string if you send one, and never the host.NONCEis inside the signed message and checked for reuse. Replaying one that already authenticated is rejected withNONCE_REUSEDeven 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
- Response codes — every code the server can return
- How to buy — funding and invoking from the CLI