tTabsdevelopers
Developer previewGitHub ↗

TABS DOCUMENTATION

Bridge V1 API#

getHost() returns the injected window.host or throws HOST_UNAVAILABLE outside Tabs. Every method returns a promise. Serialize calls: the native broker handles one privileged operation at a time. The browser bridge allows up to eight pending requests, 256 calls per visit and 64 KiB per transport envelope, with a five-minute response timeout. On host 0.0.62+, the native host renews a thirty-minute server lease every five minutes while foregrounded, and revalidates it on resume. Active visits have no fixed time limit. Closing disables the local bridge and revokes the lease; abandoned leases expire. Renewal preserves consent, replay history and budgets. Backgrounding and navigation may invalidate late results.

Method Input Result Permission
auth.getAssertion(input) {audience, nonce} {token, issuer, expiresAt} identity.authenticate
identity.getSelf() None {did, handle, displayName, avatar, appId} identity.basic
identity.resolveHandle(handle) Handle string {did, handle} social.public.read
records.create(input) {collection, value} {uri, cid} records.write
records.update(input) {collection, rkey, value} {uri, cid} records.write
records.delete(input) {collection, rkey} Empty completion (current host returns null) records.write
publicData.query(input) {collection, query?} {records, nextCursor} records.read
payments.resolve(handle) Handle string {did, handle, displayName, avatar, canReceive} payments.request
payments.request(input) {recipientDid, asset, amount, memo?} Payment result below payments.request
chat.openConversation(input) {recipientDid} Empty completion (current host returns null) chat.openConversation

Identity supplies the public profile display name and avatar URL, falling back to the handle when no display name is set. Avatars are public PDS blobs. DIDs use did:plc: followed by 24 base32 characters. Public identity is not a signed login proof for your backend; see backends.

Public records#

The collection must be declared in collections for writes or readCollections for SDK reads. A record's $type must equal the collection ID; the body must match the approved Lexicon. Records are bounded to 16 KiB JSON, 2,048 nodes and depth 16; unknown fields, NUL strings and unsafe numbers are rejected. Blob/media upload is not available through this API.

Create assigns an app-owned key. Use recordKey(result.uri, collection) to extract it. Update sends the complete replacement record, not a patch. Update/delete may target only records created by this app for this account. Your own AppView cannot infer this private ownership from a public record alone. Keep returned references for convenient editing, and plan for cache loss or a new device. There is no bridge ownership-history enumeration API yet.

const saved = await host.records.create({
  collection: "org.example.recipes.recipe",
  value: {
    $type: "org.example.recipes.recipe",
    title: "Soup",
    ingredients: [{ name: "Carrot", quantity: 2 }],
  },
});
await host.records.update({
  collection: "org.example.recipes.recipe",
  rkey: recordKey(saved.uri, "org.example.recipes.recipe"),
  value: {
    $type: "org.example.recipes.recipe",
    title: "New soup",
    ingredients: [],
  },
});

publicData.query uses Tabs' shared AppView. Optional query keys are author (DID), limit and cursor (decimal strings, default "30" and "0"). Limit is 1–100, cursor is 0–100000. Each result is {uri, cid, author: {did, handle}, record, publishedAt}. publishedAt is the index's first-seen time for generic records. nextCursor is a string or null. Public index refresh is asynchronous; offset pagination can shift during writes. Your own API can use a different query contract. See shared AppView.

Native actions#

host.payments supports USDC. Amount is a positive decimal string with at most six fractional digits and a maximum of 18446744073709.551615 USDC (the native u64 unit bound). Never calculate currency with floating-point arithmetic. Memo, if supplied, is nonempty and at most 280 UTF-8 bytes. Resolve the recipient first and retain the DID rather than substituting an unverified handle/address.

const person = await host.payments.resolve("bob.tabschat.com");
const result = await host.payments.request({
  recipientDid: person.did,
  asset: "USDC",
  amount: "0.01",
});

Results are {status: 'sent', digest}, {status: 'cancelled'}, or {status: 'pending' | 'failed' | 'expired'}. Every new transaction gets native amount/recipient confirmation and a fresh passkey, regardless of saved mini-app consent or chat login. A timeout or pending/failed/expired result is not proof of payment. Direct the user to Tabs to check the transaction; do not automatically issue another request. A fulfilment backend must verify settlement independently; JavaScript responses are not a backend payment proof. The page receives no wallet address, signing key, transaction bytes or Tabs account token.

chat.openConversation({recipientDid}) opens native UI. It provides no message history, message-send API, voice/camera access or conversation keys.

Errors and uncertain writes#

Rejected promises have a fixed error.code. Use describeError(error) for safe copy; unknown codes need a generic fallback.

Code Suggested handling
HOST_UNAVAILABLE Open in Tabs, or use the explicitly marked browser preview
PERMISSION_DENIED, FORBIDDEN Show a disabled feature; point to App permissions; never loop prompts
UNAUTHORIZED Reopen the app; the visit/account may no longer be active
INVALID_INPUT Correct the data or manifest scope
NOT_FOUND Handle missing/deleted records or unavailable recipients
BUSY Wait for the current native action
RATE_LIMITED Back off; reopening may be needed for visit limits
CONFLICT, REPLAY Refresh/reconcile; do not change and replay an uncertain write
TIMEOUT, PAYMENT_PENDING Check Tabs and reconcile before another payment/write
UNAVAILABLE or unknown Offer a later retry; do not expose raw error bodies

Each new SDK invocation receives a new operation ID. The host can retry the same transport operation idempotently, but a developer calling records.create again creates a new operation and can create a duplicate. Persist a pending UI state, refresh public data and reconcile ambiguous outcomes instead of blindly retrying.

Developer login and files#

auth.getAssertion requires host 0.0.51+, an exact allowed HTTPS backend origin, and a server-generated base64url nonce of 22–128 characters. Your backend must verify the proof and consume its own challenge once. Do not treat the public identity API as authentication. The SDK's signInWithTabs helper implements the example /auth/challenge and /auth/session protocol; the session it returns is your app's own credential. Server verification helpers live under @tabschat/miniapp-sdk/server/auth and must run in the developer backend.

files.select enables ordinary <input type="file">; it has no bridge method for arbitrary paths. SDK selectFiles({accept, multiple}) opens a normal input and returns File[] (or [] on cancellation). Invoke it directly in a click handler, then upload through fetch/FormData. The native picker has its own foreground-return validation; ordinary late bridge results still follow the background/navigation cancellation rules above. See the complete flow and limits and the runnable example.

PDS blobs (host 0.0.52+)#

host.blobs.upload(fileOrBlob, {collection}) returns a standard ATProto blob reference. Declare blobs.upload and records.write, and use a declared write collection. Binary data uses a single-use HTTPS permit, outside the JSON bridge. See media limits and protocol.

Payment fulfilment identity (host 0.0.62+)#

An app with both identity.authenticate and payments.request can request auth.getAssertion({audience, nonce, paymentAccount: true}), or use signInWithTabs({backendOrigin, paymentAccount: true}). The signed assertion includes payment_account: {network: "mainnet", senderCommitment}. The commitment is SHA-256 of tabs-miniapp-payment-v1\n<appId>\n<audience>\nmainnet\n<lowercase 0x sender address>. The host obtains the address from the active account binding; the app receives only the scoped commitment. A developer backend independently verifies settlement, amount, coin type, recipient and the chain sender against this signed commitment. The commitment is not settlement proof. Retain unique digests and idempotent orders and reconcile pending transactions before charging again. Missing wallet bindings return NOT_FOUND. Older hosts reject the optional input.

Advanced Sui wallet (host 0.0.74+)#

Declare wallet.connect plus wallet.transactions and/or wallet.messages, set minimumHostVersion to at least 0.0.74, and use advanced mode. The bridge automatically registers Tabs with Wallet Standard in the embedded app page. Standard Sui dapp clients can discover it and use connect, disconnect, events, sign transaction v2, sign-and-execute transaction v2, and personal-message signing. Only sui:mainnet is available. A connection does not approve a signature.

The portable host API exposes:

Method Input Result
wallet.connect {silent?: boolean} {accounts: [{address, publicKey, chains}]}; empty accounts on cancellation or missing silent connection
wallet.disconnect None Completion
wallet.signTransaction {address, chain: "sui:mainnet", transaction} {bytes, signature}
wallet.signAndExecuteTransaction Same transaction input {state, digest, bytes?, signature?, effects?}
wallet.signPersonalMessage {address, chain: "sui:mainnet", message} {bytes, signature}

publicKey, messages, signed transaction bytes, signatures and effects use standard base64. Transactions accept official Sui SDK v2 JSON or base64 full BCS TransactionData. For direct bridge use, serialize SDK transactions with await tx.toJSON({supportedIntents: ["CoinWithBalance"]}); the Wallet Standard adapter does this for you. The native builder resolves object references and CoinWithBalance coin/balance intents. Resolve other custom intents before sending. Each transaction/message has a native review and fresh passkey; do not supply your own trusted preview.

Customers pay general transaction gas with SUI. Missing gas price/budget can be selected by the node. Provided gas terms are retained. JSON without expiration gets a current-epoch bound. Full BCS sign-only transactions must have an epoch expiry. Sponsored transactions can use sign-only: collect the sponsor signature and submit independently. Tabs cannot execute a transaction requiring another gas owner's signature.

Personal messages are nonempty readable UTF-8, at most 4 KiB, with no opaque/control bytes except newline, carriage return and tab. Ordinary cancellation rejects with USER_REJECTED. Uncertain execution returns a pending state through the direct API; Wallet Standard rejects with TRANSACTION_PENDING and the digest. Neither is proof of failure. The user checks Activity in Tabs; do not create a replacement transaction. Sign-only authorizations remain tracked until confirmed or proven expired, and block new transfers while uncertain. Your backend independently verifies settlement.

Wallet Standard execution returns {bytes, signature, digest, effects} after successful confirmation. The adapter rejects a missing effects result instead of inventing one. Public wallet access does not expose any signing key or Tabs session token. External browser/desktop connection transport is not supplied by this embedded bridge.

Optional browser-host context#

SDK 0.2.0 adds @tabschat/miniapp-sdk/bootstrap, a side-effect entrypoint for trusted browser-host frames. It preserves native window.host. Browser bridges provide optional host.environment with kind: "browser" and mode equal to connecting, simulated or live. Check after an awaited host call. Native hosts need not provide this property. These values are UI hints; only a verified app-scoped assertion authenticates a user to your backend. See testing.