@usealbatross/sdk

@usealbatross/sdk

Official SDK for Albatross, the privacy protocol on Solana.

Move SOL privately with the bridge, or send SOL to anyone with a single unlinkable Ghost Link. No wallet connection, no signup, noncustodial.

npm install @usealbatross/sdk

Quick start

import { Albatross } from '@usealbatross/sdk'

const albatross = new Albatross()

// 1. Create a private bridge
const bridge = await albatross.createBridge({
  amount: 1,                 // SOL the recipient receives (0.1, 0.5, 1 or 5)
  destination: 'YourCleanWallet…',
})

console.log(`Send ${bridge.depositSol} SOL to ${bridge.depositAddress}`)

// 2. Wait until the payout lands
const result = await albatross.waitForBridge(bridge.id, {
  onUpdate: (s) => console.log(s.status),
})

console.log('Done:', result.payoutSignature)

Even shorter, with the one shot helper:

const { bridge, wait } = await albatross.bridge({ amount: 1, destination })
console.log(`Send ${bridge.depositSol} SOL to ${bridge.depositAddress}`)
const done = await wait()

Ghost Links

Send SOL to anyone with just a link. No address, no wallet connect, no onchain trail between sender and receiver. The claim secret lives only in the URL fragment and is never sent to or stored by the server.

import { Albatross } from '@usealbatross/sdk'

const albatross = new Albatross()

// 1. Create a Ghost Link (secret + claim URL are generated locally)
const { link, claimUrl } = await albatross.createGhostLink({
  amount: 0.5,                     // SOL the receiver claims (0.1, 0.5, 1 or 5)
  refundAddress: 'YourWallet…',    // where funds return if never claimed
  note: 'gm 👻',                    // optional, shown to the receiver
})

console.log(`Fund it: send ${link.depositSol} SOL to ${link.depositAddress}`)
console.log(`Then share: ${claimUrl}`)   // keep this safe — it can never be recovered

// 2. The receiver claims to any wallet
await albatross.claimFromUrl(claimUrl, 'ReceiverWallet…')

The secret and claimUrl are never stored server side and cannot be recovered. Persist or share them the moment you create the link.

How the bridge works

You send SOL to the fresh depositAddress. Albatross detects it and pays the same amount to your destination from an unrelated wallet. The two transfers are never linked onchain. The fee is 0.5%, added on top of the amount. Ghost Links work the same way, but the payout goes to whoever claims the link.

API

new Albatross(options?)

Option	Type	Default
baseUrl	string	https://backend.albatrossprotocol.com/api
appUrl	string	https://albatrossprotocol.com
fetch	typeof fetch	global fetch

Bridge methods

• createBridge({ amount, destination }) → Bridge — create a bridge, returns the deposit address.
• getBridge(id) → BridgeState — fetch current status.
• waitForBridge(id, opts?) → BridgeState — poll until terminal (completed, refunded, failed, expired).
• bridge({ amount, destination }) → { bridge, wait() } — create and get a ready wait() helper.
• getAmounts() → { amounts, feeBps } — selectable amounts and fee.
• getStats() → { bridges, volumeSol, fundingWallets, feeBps } — network stats.

Ghost Link methods

• createGhostLink({ amount, refundAddress, note? }) → { link, secret, claimUrl } — create a link locally hashing the secret.
• getGhostLink(id) → GhostLinkState — fetch current status.
• claimGhostLink({ id, secret, destination }) → claim to a wallet.
• claimFromUrl(claimUrl, destination) → parse a claim URL and claim it.
• waitForGhostLink(id, opts?) → poll until terminal (claimed, refunded, failed, expired).
• getGhostAmounts() → { amounts, feeBps, claimExpiryDays }.
• buildClaimUrl(id, secret) → build a shareable claim URL.
• generateClaimSecret() (named export) → { secret, secretHash } low level helper.

Statuses

Bridge: awaiting_deposit → paying_out → completed, or refunded / failed / expired.

Ghost Link: awaiting_deposit → funded → claiming → claimed, or refunded / failed / expired.

License

MIT