Proof of Stock Connect an agent

API · v0.8.0

Every call, with its price

One read-only service, three ways in: an HTTP API for code, an MCP server for agents, and a pass over x402 for when the free minute is not enough. No key, no account, no cookies. Every answer carries its time and its source.

Free60 unitsa minute per client, HTTP and MCP together. A call is 1 unit, a passport 3, a batch of n addresses ⌈n/10⌉.
Pass · x4020.01 USDCon Base for 10 minutes at 600 units a minute. Version 1 or 2, no account.
MCP7 toolsread-only, on the same limit and the same pass, at https://proofofstock.xyz/mcp.

HTTP API

free

Read-only JSON over GET at https://proofofstock.xyz. A refused request costs nothing; over the limit the answer says when to come back.

GET/verify1 unit

Is this exact contract the issuer's token on this chain? Listed or not, a look-alike or not, with the issuer list it was decided against.

params chain address

curl -s 'https://proofofstock.xyz/verify?chain=base&address=0xb20000000000000000000078ee7ce2fe4908108c'
Reference
GET/verifybatch⌈n/10⌉ units

The same check for up to 50 addresses in one call, under one issuer list and one proof.

params chain addresses

curl -s 'https://proofofstock.xyz/verify?chain=base&addresses=0xb20000000000000000000078ee7ce2fe4908108c,0xb200000000000000000000397293cb8cda9a10c5'
Reference
GET/api/find1 unit

The issuer's tokens matching a ticker, a company name or an ISIN, with their contract addresses.

params q chain

curl -s 'https://proofofstock.xyz/api/find?q=nvda'
Reference
GET/api/passport3 units

A token's whole passport: the listing, the issuer's price and its age, the on-chain premium and 24 hours of its history.

params chain address hours

curl -s 'https://proofofstock.xyz/api/passport?chain=base&address=0xb20000000000000000000078ee7ce2fe4908108c'
Reference
GET/api/overview1 unit

Per chain, the tokens whose on-chain price sits furthest from the issuer's right now.

params chain

curl -s 'https://proofofstock.xyz/api/overview?chain=base'
Reference
GET/api/impostors1 unit

Tokens that copy an issuer token's symbol or name, first flagged in the last 7 days, each with the real address.

params chain limit

curl -s 'https://proofofstock.xyz/api/impostors?chain=base&limit=5'
Reference
GET/api/matrix1 unit

Shares listed on both chains we cover: each venue's premium over its own issuer, and the gap between them.

curl -s 'https://proofofstock.xyz/api/matrix'
Reference
GET/api/history/cases1 unit

The case archive: every look-alike opened, changed, listed or gone, dated and never rewritten.

params chain event since limit

curl -s 'https://proofofstock.xyz/api/history/cases?chain=base&limit=5'
Reference
GET/api/history/registry1 unit

The issuer list as it changed, or the one in force at the end of a given day.

params chain date

curl -s 'https://proofofstock.xyz/api/history/registry?chain=base'
Reference
GET/api/archive/at1 unit

What one address was on one past day, from what was recorded that day.

params chain address date

curl -s 'https://proofofstock.xyz/api/archive/at?chain=base&address=0xb20000000000000000000078ee7ce2fe4908108c&date=2026-11-15'
Reference
GET/api/list/<hex>1 unit

The exact issuer list a verdict names, by the SHA-256 in its list_proof; /addresses gives the addresses alone. Hash it and compare.

curl -fsS https://proofofstock.xyz/api/list/<registry_hash> | sha256sum
Reference
GET/api/status1 unit

Is the data fresh: each issuer list's age, the newest price reading, the impostor list.

curl -s 'https://proofofstock.xyz/api/status'
Reference
GET/api/exam1 unit

The latest public exam: every question whose right answer comes from the issuers, and every wrong answer counted.

curl -s 'https://proofofstock.xyz/api/exam'
Reference
GET/badge.svgoutside the limit

A badge for your own page: issuer-listed, a look-alike, not listed. Cached at the edge and outside the limit.

params chain address

<img src="https://proofofstock.xyz/badge.svg?chain=base&address=0xb20000000000000000000078ee7ce2fe4908108c" alt="Proof of Stock">
Reference
GET/anchors/outside the limit

The daily manifests of our data files and their OpenTimestamps proofs in Bitcoin: /anchors/<file> serves each one.

curl -s 'https://proofofstock.xyz/anchors/'
Reference
GET/api/status/paymentsoutside the limit

The state of paid passes, for monitoring: on or off, and the settlement wallet's latest work.

curl -s 'https://proofofstock.xyz/api/status/payments'
Reference

MCP tools

free

The same answers for an agent: a public MCP server over streamable HTTP at https://proofofstock.xyz/mcp, no key. Every POST costs 1 unit; the tools below say where a call costs more. Connect an agent.

TOOLfind_stock_token1 unit

Find the issuer's tokens on one chain by ticker, company name or ISIN.

title Find a stock token · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_stock_token","arguments":{"chain":"base","query":"nvda"}}}'
Reference
TOOLlist_stock_tokens1 unit

The whole issuer list for one chain, in one answer.

title List an issuer registry · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_stock_tokens","arguments":{"chain":"base"}}}'
Reference
TOOLstock_passport3 units

One token's passport: listing, the issuer's price and its age, the premium and its history.

title Stock token passport · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"stock_passport","arguments":{"chain":"base","address":"0xb20000000000000000000078ee7ce2fe4908108c"}}}'
Reference
TOOLverify_stock_tokens⌈n/10⌉ units

Check up to 50 addresses before a buy, against the issuer's own list.

title Verify stock token addresses · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_stock_tokens","arguments":{"chain":"base","addresses":["0xb20000000000000000000078ee7ce2fe4908108c"]}}}'
Reference
TOOLrecent_impostors1 unit

Look-alikes first flagged in the last 7 days, each with the token it imitates.

title Recent impostors · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recent_impostors","arguments":{"chain":"base"}}}'
Reference
TOOLcompare_venues1 unit

The same share on both chains we cover: each venue's premium and the gap.

title Compare one share across venues · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compare_venues","arguments":{"symbol":"NVDA"}}}'
Reference
TOOLverify_anchor1 unit

Proof that a day's record has not changed: its Bitcoin proof and the mirror transactions.

title Verify a day anchor · read-only

curl -s https://proofofstock.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_anchor","arguments":{}}}'
Reference

What a free minute buys

60single checks: /verify, /api/find and the other 1-unit reads
20passports, at 3 units each
600addresses checked, in batches of 50 at ⌈50/10⌉ = 5 units

The window slides by the second: any 60 seconds, wherever a minute begins. The limit is per client address, HTTP and MCP share it, and a pass raises it for that client alone.

v0.8.0 · the full reference: HTTP API, MCP tools, fields and units, openapi.json · facts with their time and source, not investment advice.