Vulpine is a social network, a wallet and a game whose records live on the Bitcoin SV chain. Everything is public: anyone can read it, and anyone can write their own reader. This page takes you from nothing to reading and writing in a few minutes. Every example here is copied from working code.
The API is https://api.vulpinenetwork.com/api. Every Vulpine reader serves the same API, so https://fwetch.lol/api answers the same way. It is open to every website (CORS), it answers JSON, and an error comes back as {"error": "what went wrong"} with an HTTP status.
An app, a game, a wallet or a website that already exists joins the network in a minute. Nobody has to approve it, and nothing about the app has to change.
window.CWI with the person's wallet already connected, and Vulpine on a computer answers apps at http://localhost:3321, like any BRC-100 desktop wallet. If your app talks to a BRC-100 wallet, it works with Vulpine, and Fwetch's sign-in takes Vulpine, any BRC-100 desktop wallet, Yours and HandCash.https://<your site>/.well-known/vulpine.json, or the second in the <head> of the app's page.{"identity": "<your identity address>"}
<meta name="vulpine-identity" content="<your identity address>">
The reader checks when the listing arrives and every day after; Check asks again at once.
From your own code, the listing is a fwetch-app record (the protocol, 9.10.1), signed as in section 2 below:
const listing = await sign({
p: 'fwetch-app', name: 'Fox Cards', url: 'https://foxcards.example', kind: 'game',
about: 'A card game with foxes.', picture: 'https://foxcards.example/icon.png',
wallets: ['vulpine', 'brc100'], tags: ['cards'], t: Math.floor(Date.now() / 1000),
})
await fetch('https://api.vulpinenetwork.com/api/sponsor/opreturn', {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ kind: 'post', payload: listing }),
})
To change it, write a new one with replaces: '<the old txid>'; to take it down, { p: 'fwetch-app', replaces: '<txid>', gone: true }. Read the directory with GET /api/apps (?q= words, ?kind= app, game, tool, wallet or site, ?wallet= one it works with), one listing with GET /api/app/:txid.
Twetch shows a Twonk's new owner straight away only when the transfer is posted to it signed by the owner's Twetch key, which only the person's wallet holds. Vulpine 0.99.268 and later sign that request for you; Vulpine sends nothing.
// after the transfer itself went through createAction (the wallet signs the Twonk's input)
const body = JSON.stringify({ userId, collection, number, txHex }) // in that order, no spaces
const ts = Date.now()
const message = `POST\n/v1/tokens/transfer\n${userId}\n${ts}\n${body}`
const { signature } = await window.CWI.signTwetchRequest({ twetchUserId: userId, message })
await fetch('https://api.twetch.com/v1/tokens/transfer', { method: 'POST', body, headers: {
'content-type': 'application/json', 'x-twetch-user': String(userId), 'x-twetch-ts': String(ts), 'x-twetch-sig': signature } })
The wallet signs only a request for a Twonk transfer it signed itself in the last half hour, timed within ten minutes of now, for the account Twetch says the Twonk's keys are, and only after the person says yes, every time. A request that is not Twetch's transfer request (a login, a post, any other text) is refused at once with the reason. For a transfer the wallet did not make for an app in the last half hour (a list kept in memory, so a restart clears it), the person is shown that your app asked and your app gets the usual "declined" error, whatever they press. Twetch is asked only after the person's yes, and when Twetch names another account for the keys your app is told that it is not twetchUserId's, never which account it is (Vulpine 0.99.271 and later). The signature is a Bitcoin Signed Message, base64, as twetch.com signs, by the account's own key: Twetch knows an account by its phrase's m/0/0 and delivers its Twonks to m/0/1, so a Twonk held at m/0/1 is signed for by m/0/0 (Vulpine 0.99.271 and later; 0.99.268 to 270 signed only with the key that held it). It is Vulpine's own method beside the BRC-100 ones, on window.CWI inside Vulpine and at http://localhost:3321/signTwetchRequest on a computer.
To name the account, ask the wallet which Twetch account holds the Twonk (Vulpine 0.99.271 and later):
const { twetchUserId } = await window.CWI.getTwetchUserId({ outpoint: `${txid}.${vout}` })
The wallet asks the person first, every time, for any outpoint. For a Twonk it does not hold, the person is shown that your app asked and your app gets the usual "declined" error, whatever they press, the same words a no gives for one it holds, so no page can learn what a wallet holds. For one it holds, only after the person's yes does it ask Twetch which account the Twonk's keys are, and it tells your app that number and nothing else; nothing is signed or sent. When Twetch knows no account for its keys, or cannot be reached, the error is "Vulpine could not say which Twetch account holds that Twonk."
Twonks Twetch delivered to m/0/1 are in the wallet from 0.99.271 on (before it, only Twonks at keys the wallet had found by their history were, and m/0/1 has no history WhatsOnChain shows). An input of a Twonk the wallet holds is signed by the wallet with the Twonk's whole unlock whether or not you give unlockingScriptLength.
To read the account's own wallet list from Twetch (its coins and balance), have the wallet sign Twetch's read (Vulpine 0.99.306 and later). Read-only: nothing is spent or posted, and the person is asked every time.
const ts = Date.now()
// the path without its query, as twetch.com's own app signs it; the body line is empty
const message = `GET\n/v1/wallet/${userId}/onchain\n${userId}\n${ts}\n`
const { signature } = await window.CWI.signTwetchRequest({ twetchUserId: userId, message })
// add ?sync=1 to the address (not to the message) to have Twetch read the chain again first
const list = await (await fetch(`https://api.twetch.com/v1/wallet/${userId}/onchain`, { headers: {
'x-twetch-user': String(userId), 'x-twetch-ts': String(ts), 'x-twetch-sig': signature } })).json()
It is signed by the account key (m/0/0) of the Twetch phrase in the person's active wallet, once Twetch says that key is twetchUserId's; any other read is refused at once with the reason.
To put right a Twetch account whose list has fallen out of step with the chain (Twetch counting coins that were spent elsewhere), ask the wallet to do it (Vulpine 0.99.308 and later). It asks Twetch to read the chain again, then tells it of the account's own payments it missed; it shows Twetch nothing of the person's other wallets, spends nothing and posts nothing, and the person is asked every time.
const r = await window.CWI.resyncTwetch({ twetchUserId: userId })
// { checked, told, dropped, stale_left, twetchSats, chainSats, inStep }
// stale_left: satoshis Twetch still counts beyond the chain (0 when in step; null when Twetch did not say)
Only for the active wallet's Twetch account: otherwise "Your active wallet is not Twetch account N's".
To know which Twetch accounts are linked to the person's Vulpine identity without waiting for a reader to index the link, ask the wallet (Vulpine 0.99.381 and later):
const { identity, links } = await window.CWI.getTwetchLink({})
// identity: the address of the identity key your app sees
// links: [{ user, name, account, nft, t, txid, via, counted }]
// via: 'keys' (signed by the Twetch wallet's own keys) or 'payment' (proved by a payment from the account)
// counted: whether the network counts the link yet; false for one the wallet made a moment ago
It is the network's list (GET /api/twetch/links/<identity>) together with the links the wallet itself put on chain that the network does not count yet; a link the person took back in the wallet is left out at once. A link is public on chain, so the person is asked as for the identity key, once for your app. Nothing is signed or sent.
When your app sends a Sigil (an Apu Fox, a Twonk) back to a key of the person's active wallet, as at the end of a loan, hand the wallet the transaction and it shows at once (Vulpine 0.99.381 and later):
await window.CWI.internalizeAction({ tx: atomicBeef, description: 'Your fox, back from the loan',
outputs: [{ outputIndex: 0, protocol: 'basket insertion', insertionRemittance: { basket: 'sigils', tags: ['returned'] } }] })
A Sigil output locked to a key of the active wallet is shown, kept from being spent as money, and kept until the index lists it (two hours at most); your app can then name it in createAction. One locked to a key of another of the person's wallets, or of nobody's, is refused: "Output N is a Sigil locked to a key that is not in the wallet you're on". Without it the wallet still finds the fox: a Twetch wallet's account key and Twonk addresses (m/0/0 to m/0/3, and where Twetch delivers) are read again every quarter hour and at every refresh by hand, and the refresh the person presses also reads Twetch's own list of the account's NFTs, each checked against the chain.
When your createAction names a fox none of the person's wallets holds, signAction's error says which address it is at (0.99.378), and from 0.99.381 the wallet itself offers to add the Twetch wallet it is in.
An input you name that the person's wallet does not hold, given with its unlockingScriptLength (or its unlockingScript), is yours to unlock, whatever its script: a pool's output, an ordinal at your escrow address, or a Twetch Sigil held in your escrow (Vulpine 0.99.306 and later; before, a Sigil the wallet did not hold was refused). The wallet signs only its own inputs, and its prompt says what yours brings and where it goes: "the app unlocks NOOGIES #6587, which comes to your address 1…", or that it goes to an address that is not the person's. A listing bought in one transaction:
const { signableTransaction } = await window.CWI.createAction({
description: 'Buy NOOGIES #6587', inputBEEF: escrowBeef,
inputs: [{ outpoint: `${escrowTxid}.${vout}`, inputDescription: 'NOOGIES #6587', unlockingScriptLength: 141 }],
outputs: [{ lockingScript: itemToBuyer, satoshis: 1, outputDescription: 'your item' },
{ lockingScript: sellerPayout, satoshis: price, outputDescription: 'to the seller' }],
options: { signAndProcess: false, randomizeOutputs: false } })
// your co-signer checks the transaction and signs the escrow input over all of it (SIGHASH_ALL | FORKID)
await window.CWI.signAction({ reference: signableTransaction.reference, spends: { [escrowIndex]: { unlockingScript } } })
Your app sees and uses only the person's active wallet, the one they have switched to (Vulpine 0.99.306 and later): the inputs it may name, the Twetch keys that sign signTwetchRequest and answer getTwetchUserId, and the sigils, ordinals, assets, 1sat and bsv21 held baskets. Before, ordinals listed every wallet in the app, and a named input or a Twetch key could come from any of them. A Twonk in a Twetch wallet the person has not made the active one is, to your app, one the wallet does not hold.
A Twetch account's own BSV (at its account key, m/0/0) is spent only when that wallet pays alone; its change goes back to that key and the transaction goes to Twetch's own wallet broadcast as well, so Twetch's list of the account's coins stays right. A payment drawn from several wallets never uses those coins.
A person links their Twetch account to their Vulpine identity once, in Vulpine (Twonks → Twetch → Link): they type their Twetch user number, and the Twetch wallet in Vulpine signs with that account's own keys, or, when that wallet's phrase is not in Vulpine, they send the small amount Vulpine asks for from Twetch. The link is on chain until they remove it (PROTOCOL.md §9.6.6). Where a fox is comes from the chain, traced from its mint; Twetch is asked only when the chain cannot say. Your game then asks the network who holds a fox, and compares that with who signed the record in front of it:
GET /api/apu/fox/1285
{ "fox": 1285, "outpoint": "<txid>_<vout>", "holder": "1…", "onChain": true,
"twetch": { "id": 4242, "name": "…" }, "identity": "1…", "by": "address", "link": { "txid": "…", "t": 1794…, "user": 4242 } }
Count a record about fox #n only when onChain is true and identity is the record's author (the address of its pub). by says how: address, the fox is at the Twonk address the link's own key signed for; account, Twetch says the linked account holds it there. identity null: nobody has linked the account holding it. A fox that changes hands changes identity with it, so ask when the record arrives, and again on the fox's next record. Also: GET /api/apu/foxes/<identity> (an identity's foxes, each checked on chain), GET /api/twetch/linked/<user>, GET /api/twetch/links/<identity>.
curl "https://api.vulpinenetwork.com/api/feed?limit=5"
| You want | Ask for |
|---|---|
| The newest posts | GET /api/feed |
| One post | GET /api/post/:txid |
| Someone's posts | GET /api/posts-by/:address |
| Every board | GET /api/boards |
| One board | GET /api/boards/:slug |
A chat room (the troll box is global) | GET /api/chat/global/messages |
| Only messages newer than one you have | GET /api/chat/global/messages?after=:id |
| A .fox name | GET /api/name/:name |
| A user number | GET /api/handle/:number |
| Records of any kind, by type or author | GET /api/assertions?type=:type&author=:address |
| One record and its history | GET /api/assertion/:txid |
| Tartary's land, a window of districts | GET /api/tartary/map?from=0&count=100 |
| A Tartary deed, ready for a game | GET /api/tartary/deed/:parcel |
| Is the reader up? | GET /api/health |
Every route, in full: the API reference.
Everything you write is a small JSON record signed with your identity key. The reader checks the signature before it keeps anything, and the house pays the network fee, so writing costs you nothing.
Sign, in JavaScript (npm install @bsv/sdk):
import { PrivateKey, ProtoWallet, Utils } from '@bsv/sdk'
// Your identity key. Keep it: it is who you are.
const key = PrivateKey.fromRandom()
// The rule for every record: everything but pub and sig, keys sorted, as
// JSON, signed with BRC-42 and the counterparty "anyone", so anyone can check it.
async function sign(record) {
const clean = {}
for (const k of Object.keys(record).sort()) clean[k] = record[k]
const { signature } = await new ProtoWallet(key).createSignature({
data: Utils.toArray(JSON.stringify(clean), 'utf8'),
protocolID: [0, 'fwetch identity'], keyID: '1', counterparty: 'anyone',
})
return { ...record, pub: key.toPublicKey().toString(), sig: Utils.toHex(signature) }
}
Say something in the troll box:
const t = Math.floor(Date.now() / 1000), body = 'gm'
const s = await sign({ p: 'fwetch-chat', room: 'global', body, enc: '', anon: '', t })
await fetch('https://api.vulpinenetwork.com/api/chat/global', {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ pub: s.pub, sig: s.sig, t, body }),
})
To post as Anonymous, sign with anon: '1' and send anon: true. A message must be sent within five minutes of its t.
Put a record of your own on the chain. An assertion is the general record: any type you choose (lowercase letters, digits, - and _) and any JSON payload. The house pays to write it.
const record = await sign({
p: 'fwetch-assert', type: 'my-game-score', payload: { score: 1200 },
t: Math.floor(Date.now() / 1000), app: 'my-game',
})
const r = await fetch('https://api.vulpinenetwork.com/api/sponsor/opreturn', {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ kind: 'post', payload: record }),
})
const { txid } = await r.json() // your record, on the chain
Read it back with GET /api/assertion/:txid, or every one of yours with GET /api/assertions?type=my-game-score&author=:address. To replace a record, write a new one with parent: '<the old txid>'; the old one is marked as superseded. The reader limits how often one key can write, and how big a record can be. The maze's saves on the chain are records like this one.
One line, where you want it:
<script src="https://fwetch.lol/embed/trollbox.js" async></script>
It is the network's one open room, the same one the wallet, Fwetch and Gekker show, in a small window. data-width and data-height size it (360 by 440 unless you say). Or frame it yourself:
<iframe src="https://fwetch.lol/embed/trollbox" width="360" height="440" style="border:0"></iframe>
Visitors read it with nothing installed. The first time someone sends a message, the box makes a throwaway key in their browser, keeps it there, and posts as Anonymous, signed like everything else.
Every district, parcel and deed is open, in a shape game engines and NFT tools already read. See Tartary deeds, for any game or world.
A coin launched on Vulpine sells along a bonding curve; when every step sells, it graduates and is ready to list. GET https://api.vulpinenetwork.com/api/v1/graduated?since=<unix seconds> says which, with the token id, symbol, decimals, supply, icon and price. See the coins API.
Any playlist or album is plain data your app can play, with no key and no sign-in: GET https://api.vulpinenetwork.com/api/playlist/<id>/plain gives its name, cover and who made it, and each track's title, artist, album, length, cover and play, an address that plays it. The playlist's maker finds its id under </> in Vulpine's Player. Songs and albums people put out are also on the web at fwetch.lol/music.
Playlists made for your app alone. People can seal a playlist so only the apps they pick can open it. To be one of them:
PrivateKey.fromRandom() with the BSV SDK). Keep the private key where your app runs.seal (Apps, or All apps, "Playlists made for your app").import { EncryptedMessage, PrivateKey, SymmetricKey, Utils } from '@bsv/sdk'
const KEY = PrivateKey.fromWif(process.env.SEAL_WIF)
const API = 'https://api.vulpinenetwork.com/api'
const { playlists } = await (await fetch(`${API}/playlists/sealed-to/${KEY.toPublicKey().toString()}`)).json()
for (const pl of playlists) {
const key = EncryptedMessage.decrypt(Utils.toArray(pl.sealed.key, 'base64'), KEY)
const { items } = JSON.parse(Utils.toUTF8(new SymmetricKey(key).decrypt(Utils.toArray(pl.sealed.data, 'base64'))))
const { tracks } = await (await fetch(`${API}/tracks`, { method: 'POST',
headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ items }) })).json()
console.log(pl.name, tracks.map((t) => t.title))
}
The details are in the protocol.