BSocial

Complete on-chain social protocol for BSV blockchain. Posts, likes, follows, messages, reposts, and friend requests using BitcoinSchema.org standards.

When to Use

Create social content (posts, replies, reposts)
Social actions (likes, follows, friend requests)
Real-time messaging (channels, direct messages)
Query social data by address or transaction

Create via @1sat/actions (Recommended)

The createSocialPost action handles B:// + MAP + AIP construction and wallet signing.

import { createSocialPost, createContext } from '@1sat/actions'

const ctx = createContext(wallet)

const result = await createSocialPost.execute(ctx, {
  app: 'my-app',           // MAP attribution — identifies the calling application
  content: 'Hello BSV!',
  contentType: 'text/plain', // or 'text/markdown'
  tags: ['intro', 'bsv'],   // optional
})

// result: { txid, rawtx, error }

The action:

Signs with the wallet's BAP identity key via AIP (using WalletSigner from @bopen-io/templates)
Stores the 0-sat OP_RETURN output in the bsocial basket for post history
Tags outputs with MAP fields (app:my-app, type:post, tag:intro, etc.) for filtered queries

Query post history: wallet.listOutputs({ basket: 'bsocial' })

Create via CLI Scripts

Alternative for raw WIF usage without BRC-100 wallet.

Post

bun run skills/bsocial/scripts/create-post.ts <wif> "Post content" [options]

# Options:
#   --channel <name>    Post to a channel
#   --url <url>         Associate with URL
#   --tags <t1,t2>      Comma-separated tags
#   --dry-run           Build tx without broadcasting

Reply

bun run skills/bsocial/scripts/create-reply.ts <wif> <txid> "Reply content" [--tags <t1,t2>]

Like

bun run skills/bsocial/scripts/create-like.ts <wif> <txid>

Follow

bun run skills/bsocial/scripts/create-follow.ts <wif> <bapId>

Repost

bun run skills/bsocial/scripts/create-repost.ts <wif> <txid> [--context <type> --value <val>]

Message

bun run skills/bsocial/scripts/create-message.ts <wif> "Message" [options]

# Options:
#   --channel <name>    Send to channel
#   --to <bapId>        Direct message to user

Friend

bun run skills/bsocial/scripts/create-friend.ts <wif> <bapId>

Read Operations

Query social data from the BMAP API.

Posts

bun run skills/bsocial/scripts/read-posts.ts <address> [--limit 20] [--json]

Likes

bun run skills/bsocial/scripts/read-likes.ts --address <addr>
bun run skills/bsocial/scripts/read-likes.ts --txid <txid>

Follows

bun run skills/bsocial/scripts/read-follows.ts <address> [--limit 100] [--json]

Messages

bun run skills/bsocial/scripts/read-messages.ts --channel <name>
bun run skills/bsocial/scripts/read-messages.ts --address <addr>

Friends

bun run skills/bsocial/scripts/read-friends.ts <address> [--json]

Protocol Stack

[B Protocol] | [MAP Protocol] | [AIP Protocol]
   content       metadata         signature

B Protocol: Binary content storage (text, media)
MAP Protocol: Metadata key-value pairs (app, type, context)
AIP Protocol: Author signature for verification

Context Types

Context	Use Case
`tx`	Reply/like a transaction
`channel`	Post/message to named channel
`bapID`	Target specific identity
`url`	Associate with external URL

Dependencies

@1sat/actions - BRC-100 action system (recommended for wallet-based operations)
@bsv/sdk - Transaction building
@bopen-io/templates - BSocial protocol templates (Signer abstraction, BSocial class)

API

Base URL: https://bmap-api-production.up.railway.app

REST Endpoints

Endpoint	Description
`/social/post/bap/{bapId}`	Posts by BAP ID
`/social/feed/{bapId}`	Feed for BAP ID
`/social/post/{txid}/like`	Likes for a post
`/social/bap/{bapId}/like`	Likes by user
`/social/friend/{bapId}`	Friends for BAP ID
`/social/@/{bapId}/messages`	Messages for user
`/social/channels/{channelId}/messages`	Channel messages

Query API (fallback)

Query: /q/{collection}/{base64Query}
SSE: /s/{collection}/{base64Query}

Ingest

POST /ingest with { rawTx: tx.toHex() }

Friend Encryption

Friend requests use Type42 key derivation with BRC-43 invoice numbers (2-friend-{sha256(friendBapId)}) via the BRC-100 wallet.

import { Hash, Utils } from "@bsv/sdk";
const { toHex, toArray } = Utils;

const keyID = toHex(Hash.sha256(toArray(friendBapId, "utf8")));

// Get encryption pubkey for friend request
const { publicKey } = await wallet.getPublicKey({
  protocolID: [2, "friend"],
  keyID,
  counterparty: "self",
});

// Encrypt private message for friend
const { ciphertext } = await wallet.encrypt({
  protocolID: [2, "friend"],
  keyID,
  counterparty: friendIdentityKey,
  plaintext: toArray("secret message", "utf8"),
});

// Decrypt message from friend
const { plaintext } = await wallet.decrypt({
  protocolID: [2, "friend"],
  keyID,
  counterparty: friendIdentityKey,
  ciphertext,
});

bsocial

Safety Notice

Copy this and send it to your AI assistant to learn