TapeAPI: signed BNB Chain reads

TapeAPI

Tape out a circuit, and its container is your API. Every response is signed by it, anyone can verify it against the chain, and containers can talk to each other over end-to-end encrypted channels.

TapeAPI is the service and communication layer of the TapeOut ecosystem on BNB Chain. In that ecosystem, DeWEB is websites, TapeSend is messaging, and TapeAPI is services.

[CI] [Code: MIT] [Spec: CC0-1.0] [Docs] [Playground] [Status]

中文说明 · Guides · Specifications · Examples · Docs · Website · Changelog · Roadmap · Contributing · Code of Conduct

Status: pre-alpha (v0.4.0). The free tier needs no contract of ours and runs on TapeOut's deployed contracts. Our own contracts (the paid-call escrow, the service directory, ChannelBus) are not audited by a third party; ChannelBus is deployed (address below). Interfaces may still change. The TAP numbers below are proposed to the TapeKit maintainers and not yet assigned.

Try the live service in 30 seconds

A free public service runs at https://api.tapeapi.fun under the TapeOut name 11.1013.tape. Ask it for the BNB price:

curl -s https://api.tapeapi.fun/tapeapi/v1/bnbUsd -H 'content-type: application/json' -d '{"id":"1","params":{}}'

curl shows you the signed envelope (result, container, ts, block, sig) but does not check it. The SDK does. The packages are not on npm yet, so set up the repository once (Node.js 20 or later):

git clone https://github.com/BruceLanLan/tapeapi.git && cd tapeapi && npm install

Or install just the SDK into your own project from the GitHub release (not the npm registry):

npm install https://github.com/BruceLanLan/tapeapi/releases/download/v0.4.0/tapeapi-sdk-0.4.0.tgz

Save this as try.mjs inside the tapeapi directory (@tapeapi/sdk resolves through the repository's workspace; a script saved anywhere else fails with ERR_MODULE_NOT_FOUND) and run node try.mjs:

import { createTapeAPI } from '@tapeapi/sdk'
const api = createTapeAPI({  rpcUrls: ['https://bsc-dataseed.bnbchain.org', 'https://bsc-dataseed1.defibit.io', 'https://bsc-dataseed1.ninicoin.io'],  quorum: 2,})const svc = await api.resolve('11.1013.tape')             // name -> container -> on-chain manifest -> holder's delegationconst { result, verified } = await api.call(svc, 'bnbUsd', {})console.log(result, verified)                              // verified is true only after the signature checked out

No install at all: the playground runs the same SDK in the browser. Every method of the public service is listed in Public API.

Use it from Claude, Cursor or any MCP client

The same eight methods are MCP tools at https://api.tapeapi.fun/mcp (Streamable HTTP, no key). In Claude, add it under Settings > Connectors > Add custom connector; in Cursor, add it to mcp.json:

{ "mcpServers": { "tapeapi": { "url": "https://api.tapeapi.fun/mcp" } } }

Every result is signed by the service's on-chain delegated key and carries a receipt with a verification link that anyone can check against the chain. The remote server signs its answers; the local command tapeapi-mcp, in the SDK's release package, checks every answer itself before the model sees it. Setup for each client, receipts and limits: MCP guide.

Why TapeAPI

An API today is a URL plus an account plus trust. You sign up with the vendor, you trust whatever its server says, and the vendor can change the answer, the price or the rules at any time.

TapeAPI makes the identity of a service an on-chain object and every answer a signed statement:

• The service is a circuit. Whoever holds the circuit NFT owns the service. Transfer the NFT and the service moves with it; nobody can take the name away.
• Every answer is signed and bound to your request. A client checks the signature against a key the circuit's holder authorised on chain. A tampered, replayed or unsigned answer is an error, never a result.
• No sign-up, no API keys. Free methods are just called. Paid methods are paid with off-chain vouchers that settle on chain in batches; the protocol takes zero fees.
• Private channels between containers. Two services, two agents or two apps can open an end-to-end encrypted channel, carried by a relay or by the chain itself, where the carrier only ever sees ciphertext.

How it works

sequenceDiagram    autonumber    participant C as Client (SDK)    participant B as BNB Chain    participant S as Service    C->>B: resolve: circuit -> container (DeWebHub), holder (ownerOf)    C->>B: read the manifest from the container's site (SiteRegistry, SHA-256 checked)    Note over C: check the holder's EIP-712 delegation of the service's signing key    C->>S: POST /tapeapi/v1/{method} { id, params, voucher? }    S-->>C: { result, container, ts, block, sig }    Note over C: verify the signature over the request and the answer; only then return the result

1. Identity (TAP-20). A circuit's ERC-6551 container is the service identity. Its site holds .well-known/tapeapi.json, the manifest: endpoints, methods, prices and the service's signing key.
2. Delegation. The circuit's holder signs an EIP-712 delegation that names that signing key and an expiry. The domain is anchored on TapeOut's deployed DeWebHub, so a service works before any contract of ours exists.
3. Signed envelope (TAP-21). Every answer, success or error, is signed over a digest that binds the container, the request id, the method and parameters, the result and a timestamp.
4. Payment (TAP-22). Paid methods take cumulative vouchers, settled from a per-provider escrow channel.
5. Channels (TAP-26, TAP-27). Holder-authorised channel keys, an X3DH-style handshake and ChaCha20-Poly1305 frames, over a relay or over ChannelBus, a stateless event-only contract.

Quick start

Requirements: Node.js 20 or later. The packages are not on npm yet; use the repository.

git clone https://github.com/BruceLanLan/tapeapi.gitcd tapeapinpm install

Call a service

Run the minimal example service locally (it reads BNB Chain through public nodes):

node examples/reader-service/index.mjs        # listens on :8787 with a throwaway signing key

Call it from code. The SDK resolves the manifest, calls the method and verifies the signature before it returns:

import { createTapeAPI } from '@tapeapi/sdk'
const api = createTapeAPI({ dev: true })                           // dev: allow a local http:// serviceconst svc = await api.resolve({ dev: 'http://127.0.0.1:8787' })const { result, verified } = await api.call(svc, 'blockNumber', {})console.log(result.blockNumber, verified)

On mainnet, resolve by TapeOut name, container address or circuit, with at least two RPC nodes that must agree:

const api = createTapeAPI({  rpcUrls: ['https://bsc-dataseed.bnbchain.org', 'https://bsc-dataseed1.defibit.io', 'https://bsc-dataseed1.ninicoin.io'],  quorum: 2,})const svc = await api.resolve('0x<container>')                     // or '11.1013.tape', or { circuits: '0x…', tokenId: '11' }const { result } = await api.call(svc, 'blockNumber', {})

Or with curl, and verify by hand later (how):

curl -s -X POST http://127.0.0.1:8787/tapeapi/v1/blockNumber \  -H 'content-type: application/json' -d '{"id":"1","params":{}}'

Run a service

Wrap any function, or any existing REST API, as a signed method:

import { createProvider } from '@tapeapi/server'
const provider = createProvider({  manifest,                                  // your tapeapi.json  signerKey: process.env.SIGNER_KEY,         // the key the circuit's holder delegates to  rpcUrls: [/* >= 2 BNB Chain nodes */], quorum: 2,  methods: {    blockNumber: async (_params, ctx) => ({ blockNumber: ctx.block }),    quote: async ({ symbol }) => fetch(`https://your.api/quote/${symbol}`).then((r) => r.json()),  },})await provider.listen(8787)                  // Node; on Cloudflare Workers use provider.handleRequest(request)

Going live takes a circuit with an opened container, a delegation signed by its holder, and the manifest written to the container's site. The holder console does all three from a phone wallet. See Run a service.

Features

Packages and repository layout

Specifications

On-chain addresses (BNB Chain, chainId 56)

Quality

• Tests: about 710 JavaScript tests (npm test), 169 Foundry tests (cd contracts && forge test), and 102 checks by an independent Python implementation of the signatures, hashes and encodings (python3 spec/vectors/verify.py).
• Adversarial review: twelve rounds of review with a written finding, a failing test and a fix for each; the on-chain reader is covered by a randomised test of faulty, lying and noisy nodes, reorgs and room changes.
• Recorded reality: what real BNB Chain nodes answer (history refusals, result caps, lagging backends) is recorded from mainnet and replayed in tests.
• Not yet: an external audit of the contracts. Do not hold funds you cannot afford to lose in the escrow.

Security

Report vulnerabilities privately, as described in SECURITY.md. Please do not open public issues for security problems.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Specification changes go through the TAP process in TAP-1. All three test suites must pass.

License

Code is MIT (LICENSE): contracts/, sdk/, server/, examples/, conformance/, scripts/, site/. The specifications in spec/ are CC0-1.0 (LICENSE-SPEC).

Credits

The idea of a service layer for TapeOut, "DeWEB is websites, TapeSend is messaging, TapeAPI is services", came from @Theairresearch. A permanent 10% of any revenue TapeAPI earns goes to them.

Built on TapeOut and TapeKit.