diff --git a/content/docs/sdk/all-modules.mdx b/content/docs/sdk/all-modules.mdx
index 45d896e2..d75acb5c 100644
--- a/content/docs/sdk/all-modules.mdx
+++ b/content/docs/sdk/all-modules.mdx
@@ -41,6 +41,7 @@ Swidge is the preferred interface for new protocol providers that can quote and
|--------|----------|-------------|---------------|
| [`wdk-protocol-swidge-orchestra`](https://www.npmjs.com/package/wdk-protocol-swidge-orchestra) | Flashnet Orchestra | Swidge provider for BTC and stablecoin routes returned by Orchestra. Treat the live [Orchestra route matrix](https://orchestration.flashnet.xyz/v1/orchestration/routes) as provider-level data and filter through package discovery before exposing routes. | [Docs](/sdk/swidge-modules/swidge-orchestra/) |
| [`@rhino.fi/wdk-protocol-swidge-rhinofi`](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) | Rhino.fi | Swidge routes for Rhino.fi cross-chain swap and bridge operations | [Docs](/sdk/swidge-modules/swidge-rhinofi/) |
+| [`@gobob/wdk-protocol-swidge-gateway`](https://www.npmjs.com/package/@gobob/wdk-protocol-swidge-gateway) | BOB Gateway | Native BTC swidge routes to and from tokens on EVM chains and Tron, settled on Bitcoin L1 with no wrapped-BTC intermediary | [Docs](/sdk/swidge-modules/swidge-gateway/) |
## Pricing Modules
@@ -96,3 +97,4 @@ Modules built by the WDK community. See the [Community Modules](/sdk/community-m
| [`@morpho-org/wdk-protocol-lending-morpho-evm`](https://www.npmjs.com/package/@morpho-org/wdk-protocol-lending-morpho-evm) | EVM | Morpho Vault V2 and Morpho Blue lending integration | [Docs](/sdk/lending-modules/lending-morpho-evm/) |
| [`wdk-protocol-swidge-orchestra`](https://github.com/flashnetxyz/wdk-protocol-swidge-orchestra) | Swidge | Flashnet Orchestra BTC and stablecoin route integration | [Docs](/sdk/swidge-modules/swidge-orchestra/) |
| [`@rhino.fi/wdk-protocol-swidge-rhinofi`](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) | Rhino.fi | Swidge cross-chain route integration | [Docs](/sdk/swidge-modules/swidge-rhinofi/) |
+| [`@gobob/wdk-protocol-swidge-gateway`](https://github.com/bob-collective/wdk-protocol-swidge-gateway) | Swidge | BOB Gateway native BTC route integration | [Docs](/sdk/swidge-modules/swidge-gateway/) |
diff --git a/content/docs/sdk/community-modules/index.mdx b/content/docs/sdk/community-modules/index.mdx
index a0d4a118..8378f65f 100644
--- a/content/docs/sdk/community-modules/index.mdx
+++ b/content/docs/sdk/community-modules/index.mdx
@@ -23,6 +23,7 @@ Tether and the WDK Team do not endorse or assume responsibility for their code,
| [@morpho-org/wdk-protocol-lending-morpho-evm](https://www.npmjs.com/package/@morpho-org/wdk-protocol-lending-morpho-evm) ([GitHub](https://github.com/morpho-org/sdks/tree/main/packages/wdk-protocol-lending-morpho-evm)) | Lending Module | Morpho EVM lending module for vault deposits, collateral supply, borrowing, repayment, and position reads | [Docs](/sdk/lending-modules/lending-morpho-evm/) | [Morpho Association](https://morpho.org/) |
| [wdk-protocol-swidge-orchestra](https://www.npmjs.com/package/wdk-protocol-swidge-orchestra) ([GitHub](https://github.com/flashnetxyz/wdk-protocol-swidge-orchestra)) | Swidge Module | Flashnet Orchestra Swidge provider for BTC and stablecoin routes returned by Orchestra | [Docs](/sdk/swidge-modules/swidge-orchestra/) | [Flashnet](https://github.com/flashnetxyz) |
| [@rhino.fi/wdk-protocol-swidge-rhinofi](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) ([GitHub](https://github.com/rhinofi/wdk-protocol-swidge-rhinofi)) | Swidge Module | Rhino.fi cross-chain swap and bridge routes through the WDK swidge interface | [Docs](/sdk/swidge-modules/swidge-rhinofi/) | [Rhino.fi](https://rhino.fi/) |
+| [@gobob/wdk-protocol-swidge-gateway](https://www.npmjs.com/package/@gobob/wdk-protocol-swidge-gateway) ([GitHub](https://github.com/bob-collective/wdk-protocol-swidge-gateway)) | Swidge Module | Native BTC swidge routes to and from tokens on EVM chains and Tron, settled on Bitcoin L1 with no wrapped-BTC intermediary and no custodian | [Docs](/sdk/swidge-modules/swidge-gateway/) | [BOB](https://gobob.xyz) |
---
diff --git a/content/docs/sdk/swidge-modules/index.mdx b/content/docs/sdk/swidge-modules/index.mdx
index c30b1db2..3640af48 100644
--- a/content/docs/sdk/swidge-modules/index.mdx
+++ b/content/docs/sdk/swidge-modules/index.mdx
@@ -27,6 +27,8 @@ Use the existing [swap modules](/sdk/swap-modules) and [bridge modules](/sdk/bri
| Module | Provider | Routes | Documentation |
|--------|----------|--------|---------------|
| [`wdk-protocol-swidge-orchestra`](https://www.npmjs.com/package/wdk-protocol-swidge-orchestra) ([GitHub](https://github.com/flashnetxyz/wdk-protocol-swidge-orchestra)) | Flashnet Orchestra | BTC and stablecoin routes returned by Orchestra. Treat the live [Orchestra route matrix](https://orchestration.flashnet.xyz/v1/orchestration/routes) as provider-level data and filter through runtime discovery before exposing routes. | [Docs](/sdk/swidge-modules/swidge-orchestra/) |
+| [`@rhino.fi/wdk-protocol-swidge-rhinofi`](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) ([GitHub](https://github.com/rhinofi/wdk-protocol-swidge-rhinofi)) | Rhino.fi | Cross-chain swap and bridge routes from EVM source accounts. | [Docs](/sdk/swidge-modules/swidge-rhinofi/) |
+| [`@gobob/wdk-protocol-swidge-gateway`](https://www.npmjs.com/package/@gobob/wdk-protocol-swidge-gateway) ([GitHub](https://github.com/bob-collective/wdk-protocol-swidge-gateway)) | BOB Gateway | Native BTC routes to and from tokens on EVM chains and Tron. Real BTC on Bitcoin L1, with no wrapped-BTC intermediary and no custodian. | [Docs](/sdk/swidge-modules/swidge-gateway/) |
## Interface methods
@@ -209,6 +211,9 @@ Register and use protocol modules with WDK accounts
Use the Flashnet Orchestra community Swidge provider
+
+Swidge native BTC to and from tokens on EVM chains and Tron
+
Maintain existing standalone swap modules
diff --git a/content/docs/sdk/swidge-modules/swidge-gateway/configuration.mdx b/content/docs/sdk/swidge-modules/swidge-gateway/configuration.mdx
new file mode 100644
index 00000000..5fdb2e37
--- /dev/null
+++ b/content/docs/sdk/swidge-modules/swidge-gateway/configuration.mdx
@@ -0,0 +1,124 @@
+---
+title: BOB Gateway Swidge Configuration
+description: Configuration options for @gobob/wdk-protocol-swidge-gateway.
+docType: reference
+schemaType: TechArticle
+icon: Settings
+---
+
+`GatewaySwidge` works with no configuration beyond a source chain. The module ships a default API endpoint and a default attribution token, so a minimal setup is enough to quote and execute.
+
+```javascript
+import { GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway'
+
+const gateway = new GatewaySwidge(account, {
+ fromChain: 'bitcoin'
+})
+```
+
+## Constructor
+
+```typescript
+new GatewaySwidge(account?, config?)
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `account` | WDK wallet account for the source chain — a `@tetherto/wdk-wallet-btc` account for BTC sources, or a `@tetherto/wdk-wallet-evm` (or ERC-4337) account for token sources. Quoting and discovery work without a writable account. |
+| `config` | Optional `GatewaySwidgeConfig`. Set `fromChain` here unless you pass it per call. |
+
+## Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `fromChain` | `string` | Source chain identifier, for example `'bitcoin'`, `'ethereum'`, or `'base'`. Required unless supplied in the route options. |
+| `slippage` | `number` | Default slippage tolerance as a decimal. Defaults to `0.03` (3%). Override per call in the route options. |
+| `affiliates` | `Array<{ address: string, bps: number }>` | Affiliate fee entries, in basis points, credited to each address. Applies to BTC to EVM and EVM to BTC routes only. |
+| `feeRate` | `number` | Bitcoin fee rate in sat/vByte for onramp transactions. Defaults to a gateway-supplied estimate. |
+| `paymasterToken` | `string` | ERC-20 token used to pay gas on ERC-4337 accounts. |
+| `bearerToken` | `string` | Gateway API bearer token. Defaults to BOB's shared attribution key — see [API access](#api-access). |
+| `apiUrl` | `string` | Gateway API base URL override. |
+| `http` | `object` | Injectable HTTP transport. Useful for tests and custom runtimes. |
+| `client` | `GatewayClient` | A pre-built client instance. Overrides `apiUrl`, `bearerToken`, and `http`. |
+
+## Source Chain
+
+The module signs on the source chain, so `fromChain` decides which WDK account it needs. Create one `GatewaySwidge` instance per source chain.
+
+```javascript
+// BTC as the source: pass a WDK Bitcoin account.
+const fromBtc = new GatewaySwidge(btcAccount, { fromChain: 'bitcoin' })
+
+// A token as the source: pass a WDK EVM account.
+const fromBase = new GatewaySwidge(evmAccount, { fromChain: 'base' })
+```
+
+## Slippage
+
+Set a default in the constructor and override it for a single route when needed.
+
+```javascript
+const gateway = new GatewaySwidge(account, {
+ fromChain: 'bitcoin',
+ slippage: 0.01 // 1%
+})
+
+const quote = await gateway.quoteSwidge({
+ ...options,
+ slippage: 0.005 // 0.5% for this route only
+})
+```
+
+## Affiliate Fees
+
+Charge a fee on BTC to EVM and EVM to BTC routes by crediting one or more addresses in basis points of the input amount. Affiliate fees are not supported on EVM-to-EVM routes.
+
+```javascript
+const gateway = new GatewaySwidge(account, {
+ fromChain: 'bitcoin',
+ affiliates: [{ address: '0xYourFeeRecipient...', bps: 25 }] // 0.25%
+})
+```
+
+Affiliate fees appear in the quote's itemized `fees` array with type `affiliate`, so a UI can display them before the user confirms.
+
+## API Access
+
+Every request carries a bearer token. If you do not set one, the module sends BOB's shared `gateway-wdk` attribution key, which costs nothing extra and attributes the volume to BOB.
+
+```javascript
+// Uses BOB's default attribution key.
+const gateway = new GatewaySwidge(account, { fromChain: 'bitcoin' })
+
+// Uses your own key. Set this only if you have a direct API agreement with BOB.
+const gateway = new GatewaySwidge(account, {
+ fromChain: 'bitcoin',
+ bearerToken: process.env.GATEWAY_API_KEY
+})
+```
+
+
+The Gateway API applies a **country blocklist** that includes the United States and the United Kingdom alongside sanctioned jurisdictions. Requests from a blocked country receive a `403`. See the [Gateway FAQ](https://docs.gobob.xyz/gateway/faq#are-any-regions-blocked-from-using-gateway) for the current list. CI that exercises live quotes must run from a non-blocked region.
+
+
+## Bitcoin Fee Rate
+
+Onramp transactions use a gateway-supplied fee estimate by default. Override it when your app already tracks mempool conditions.
+
+```javascript
+const gateway = new GatewaySwidge(btcAccount, {
+ fromChain: 'bitcoin',
+ feeRate: 12 // sat/vByte
+})
+```
+
+## ERC-4337 Accounts
+
+Pass `paymasterToken` to pay gas in an ERC-20 when the source account is an ERC-4337 smart account from `@tetherto/wdk-wallet-evm-erc-4337`.
+
+```javascript
+const gateway = new GatewaySwidge(smartAccount, {
+ fromChain: 'base',
+ paymasterToken: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2' // USDT on Base
+})
+```
diff --git a/content/docs/sdk/swidge-modules/swidge-gateway/index.mdx b/content/docs/sdk/swidge-modules/swidge-gateway/index.mdx
new file mode 100644
index 00000000..ad34e6b7
--- /dev/null
+++ b/content/docs/sdk/swidge-modules/swidge-gateway/index.mdx
@@ -0,0 +1,72 @@
+---
+title: BOB Gateway Swidge Overview
+description: Overview of the @gobob/wdk-protocol-swidge-gateway module for native BTC swap and bridge routes.
+docType: explanation
+schemaType: TechArticle
+---
+
+The BOB Gateway Swidge module lets WDK accounts quote and execute **native Bitcoin** swap and bridge routes through [BOB Gateway](https://gobob.xyz) using the shared `SwidgeProtocol` interface.
+
+Use this module when an app needs to move real BTC in or out of tokens on EVM chains and Tron. Bitcoin is spent and received on Bitcoin L1 — there is no wrapped-BTC intermediary and no custodian, and keys never leave the WDK account.
+
+## Features
+
+- **Unified route interface**: Implements `quoteSwidge()`, `swidge()`, `getSwidgeStatus()`, `getSupportedChains()`, and `getSupportedTokens()`.
+- **Native BTC routes**: Swaps native BTC to and from USDT, USDC, ETH, wBTC, cbBTC, and XAUT across Ethereum, Base, Arbitrum, and BSC.
+- **BTC to Tron**: Sends BTC and receives USDT (or other supported tokens) on Tron.
+- **EVM to EVM**: Same-chain swaps and cross-chain bridges through the inherited `swap()` and `bridge()` methods.
+- **Non-custodial**: Signing is delegated to the WDK account. The module never touches private keys.
+- **Affiliate fees**: Optional per-address basis-point fees on BTC to EVM and EVM to BTC routes.
+- **Approval pre-flight**: `getRequiredApproval()` reports the exact ERC-20 approval an offramp needs before execution.
+- **Multi-runtime**: Runs on Node.js, Bare (`bare.js`), and React Native.
+- **Typed errors**: Exposes `GatewaySwidgeError` with stable `ERR` codes for HTTP, validation, unsupported route, and approval failures.
+
+## Supported Routes
+
+Call `getSupportedChains()` and `getSupportedTokens()` at runtime — BOB Gateway controls the live route set and adds chains and tokens over time.
+
+| Route | Source support | Notes |
+|-------|----------------|-------|
+| BTC to EVM (onramp) | Supported | Spends native BTC from a `@tetherto/wdk-wallet-btc` account. Supports affiliate fees. |
+| EVM to BTC (offramp) | Supported | Spends an ERC-20 from a `@tetherto/wdk-wallet-evm` account. Requires an approval first. Supports affiliate fees. |
+| BTC to Tron | Supported | Tron is a **destination only**. Tron as a source is not supported; see the [Tron source tracking issue](https://github.com/tetherto/wdk-wallet-tron/issues/48). |
+| EVM to EVM | Supported | Use the inherited `swap()` and `bridge()` methods. Affiliate fees do not apply to this route. |
+| Solana | Not yet available | Planned. |
+
+## Execution Model
+
+The route direction determines which chain the module signs on.
+
+**Onramp (BTC to a token).** `swidge()` builds and signs a Bitcoin transaction through the WDK BTC account, then hands it to the gateway. **The gateway broadcasts the Bitcoin transaction — the module does not.** The call resolves once the transaction is registered; the destination tokens settle asynchronously.
+
+**Offramp (a token to BTC).** `swidge()` submits the source-chain EVM transaction after the required ERC-20 approval is in place. It resolves once that transaction is broadcast, and BTC settles on Bitcoin L1 asynchronously.
+
+In both directions, use `getSwidgeStatus(result.id)` to track the route to completion.
+
+
+`swidge()` spends real funds and can submit a Bitcoin or EVM transaction. Show the quote, fee breakdown, recipient, source token, destination token, and destination chain, and ask for explicit user confirmation before calling it.
+
+
+
+The Gateway API applies a **country blocklist** that includes the United States and the United Kingdom alongside sanctioned jurisdictions. Requests from a blocked country receive a `403`. See the [Gateway FAQ](https://docs.gobob.xyz/gateway/faq#are-any-regions-blocked-from-using-gateway) for the current list, and account for it in both production deployments and CI.
+
+
+## Next Steps
+
+
+
+Configure the source chain, slippage, affiliate fees, BTC fee rate, and API access.
+
+
+Install the package, register the module, quote a route, approve, execute, and poll status.
+
+
+Review constructor options, methods, route options, status mapping, and error codes.
+
+
+
+---
+
+## Need Help?
+
+
diff --git a/content/docs/sdk/swidge-modules/swidge-gateway/usage.mdx b/content/docs/sdk/swidge-modules/swidge-gateway/usage.mdx
new file mode 100644
index 00000000..5b9ace6a
--- /dev/null
+++ b/content/docs/sdk/swidge-modules/swidge-gateway/usage.mdx
@@ -0,0 +1,216 @@
+---
+title: BOB Gateway Swidge Usage
+description: Install, register, quote, approve, execute, and track native BTC swidge routes with BOB Gateway.
+docType: how-to
+schemaType: TechArticle
+---
+
+This guide shows how to [install the package](#install-the-package), [register the module](#register-the-module), [quote a route](#quote-a-route), [swap BTC for a token](#onramp-btc-to-a-token), [swap a token for BTC](#offramp-a-token-to-btc), and [track status](#track-status).
+
+## Install the package
+
+Install the module and the WDK wallet base package. `@tetherto/wdk-wallet` is a **peer** dependency: the module must extend the same `SwidgeProtocol` base class your WDK core resolves, or registration will not take effect.
+
+```bash title="Install BOB Gateway Swidge"
+npm install @gobob/wdk-protocol-swidge-gateway @tetherto/wdk-wallet
+```
+
+Install WDK core and the wallet modules for the chains you support:
+
+```bash title="Install WDK wallet modules"
+npm install @tetherto/wdk @tetherto/wdk-wallet-btc @tetherto/wdk-wallet-evm
+```
+
+## Register the module
+
+Register a wallet for each chain you support, then register `GatewaySwidge` against the **source** chain. The module signs on the source chain, so register it once per source you offer.
+
+```javascript title="Register BOB Gateway on Bitcoin and Base"
+import WDK from '@tetherto/wdk'
+import WalletManagerBtc from '@tetherto/wdk-wallet-btc'
+import WalletManagerEvm from '@tetherto/wdk-wallet-evm'
+import { GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway'
+
+const wdk = new WDK(seedPhrase)
+ .registerWallet('bitcoin', WalletManagerBtc, {
+ network: 'bitcoin',
+ client: {
+ type: 'electrum',
+ clientConfig: {
+ host: 'electrum.blockstream.info',
+ port: 50001
+ }
+ }
+ })
+ .registerWallet('base', WalletManagerEvm, {
+ chainId: 8453,
+ provider: process.env.BASE_RPC_URL
+ })
+ .registerProtocol('bitcoin', 'gateway', GatewaySwidge, { fromChain: 'bitcoin' })
+ .registerProtocol('base', 'gateway', GatewaySwidge, { fromChain: 'base' })
+
+const btcAccount = await wdk.getAccount('bitcoin', 0)
+const baseAccount = await wdk.getAccount('base', 0)
+
+const fromBtc = btcAccount.getSwidgeProtocol('gateway')
+const fromBase = baseAccount.getSwidgeProtocol('gateway')
+```
+
+You can also construct the module directly, without WDK core:
+
+```javascript title="Direct instantiation"
+import { GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway'
+
+const fromBtc = new GatewaySwidge(btcAccount, { fromChain: 'bitcoin' })
+```
+
+## Discover supported routes
+
+BOB Gateway controls the live route set. Query it at runtime rather than hardcoding chains and tokens.
+
+```javascript title="Discover chains and tokens"
+const chains = await fromBtc.getSupportedChains()
+const tokens = await fromBtc.getSupportedTokens({ toChain: 'base' })
+```
+
+## Quote a route
+
+Quote before executing so the user can review the destination amount and the fee breakdown. Pass `'BTC'` (or the exported `BTC` constant) as the token identifier for native Bitcoin; use the contract address for ERC-20 and TRC-20 tokens.
+
+```javascript title="Quote BTC to USDT on Base"
+import { BTC } from '@gobob/wdk-protocol-swidge-gateway'
+
+const options = {
+ fromToken: BTC,
+ toToken: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', // USDT on Base
+ toChain: 'base',
+ recipient: '0xRecipient...',
+ fromTokenAmount: 100000n // satoshis
+}
+
+const quote = await fromBtc.quoteSwidge(options)
+
+console.log('Expected output:', quote.toTokenAmount)
+console.log('Minimum output:', quote.toTokenAmountMin)
+console.log('Fees:', quote.fees)
+```
+
+Amounts are always in the token's smallest unit — satoshis for BTC, and the token's own decimals for ERC-20 and TRC-20 tokens.
+
+## Onramp: BTC to a token
+
+Show the quote, get explicit confirmation, then execute with the same route options. The module signs a Bitcoin transaction through the WDK BTC account; **the gateway broadcasts it**.
+
+```javascript title="Swap native BTC for USDT on Base"
+const quote = await fromBtc.quoteSwidge(options)
+// Display the quote and ask the user to confirm before continuing.
+
+const result = await fromBtc.swidge(options)
+
+console.log('Order ID:', result.id)
+console.log('Bitcoin transaction:', result.hash)
+```
+
+No approval is needed on this route: BTC is a native asset.
+
+## Offramp: a token to BTC
+
+An ERC-20 source needs an allowance before execution. Ask the module what approval the route requires, grant it through the WDK account, then execute.
+
+```javascript title="Swap USDT on Base for native BTC"
+const options = {
+ fromToken: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', // USDT on Base
+ toToken: BTC,
+ toChain: 'bitcoin',
+ recipient: 'bc1qRecipient...',
+ fromTokenAmount: 10000000n // 10 USDT (6 decimals)
+}
+
+const approval = await fromBase.getRequiredApproval(options)
+
+if (approval) {
+ await baseAccount.approve(approval.token, approval.spender, approval.amount)
+}
+
+const result = await fromBase.swidge(options)
+
+console.log('Order ID:', result.id)
+console.log('Source transaction:', result.hash)
+```
+
+
+`getRequiredApproval()` creates a gateway order internally on a cache miss to discover the spender address, and caches the result per route on the instance. Call it once per route and reuse the result — do not call it before every swap.
+
+
+
+**USDT on Ethereum** rejects an allowance change from one non-zero value to another. If the account already holds a non-zero allowance for the spender, reset it to `0n` first, then approve the required amount.
+
+```javascript
+await evmAccount.approve(approval.token, approval.spender, 0n)
+await evmAccount.approve(approval.token, approval.spender, approval.amount)
+```
+
+
+## EVM to EVM
+
+Same-chain swaps and cross-chain bridges use the inherited `swap()` and `bridge()` methods. Affiliate fees do not apply to these routes.
+
+```javascript title="Swap USDC for USDT on Base"
+const result = await fromBase.swap({
+ tokenIn: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+ tokenOut: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', // USDT on Base
+ tokenInAmount: 1000000n
+})
+```
+
+## Track status
+
+Bitcoin settlement is asynchronous in both directions. Poll with the order ID returned by `swidge()`.
+
+```javascript title="Poll a swidge to completion"
+const status = await fromBtc.getSwidgeStatus(result.id)
+
+if (status.status === 'completed') {
+ console.log('Settled:', status.transactions)
+}
+```
+
+Gateway order states map onto the canonical WDK `SwidgeStatus` values:
+
+| Gateway state | WDK status |
+|---------------|------------|
+| In progress, or awaiting the Bitcoin payment | `pending` |
+| Success | `completed` |
+| Failed | `failed` |
+| Refunded | `refunded` |
+
+## Handle errors
+
+Failures throw a `GatewaySwidgeError` carrying a stable `code` from `ERR`, plus the HTTP `status` where one applies.
+
+```javascript title="Handle module errors"
+import { GatewaySwidgeError, ERR } from '@gobob/wdk-protocol-swidge-gateway'
+
+try {
+ await fromBtc.swidge(options)
+} catch (err) {
+ if (err instanceof GatewaySwidgeError) {
+ switch (err.code) {
+ case ERR.UNSUPPORTED_ROUTE:
+ // The requested token or chain pair has no gateway route.
+ break
+ case ERR.APPROVAL_REQUIRED:
+ // Grant the approval from getRequiredApproval() first.
+ break
+ case ERR.VALIDATION:
+ // The route options are incomplete or inconsistent.
+ break
+ case ERR.HTTP:
+ // Transport or API failure. Inspect err.status.
+ break
+ }
+ }
+}
+```
+
+A `403` on `ERR.HTTP` usually means the request came from a blocked country. See [Configuration](/sdk/swidge-modules/swidge-gateway/configuration#api-access).
diff --git a/src/lib/custom-tree.ts b/src/lib/custom-tree.ts
index aa7f6529..c50690f8 100644
--- a/src/lib/custom-tree.ts
+++ b/src/lib/custom-tree.ts
@@ -266,6 +266,11 @@ export const customTree: Node[] = [
configuration('/sdk/swidge-modules/swidge-rhinofi/configuration'),
apiReference('/sdk/swidge-modules/swidge-rhinofi/api-reference'),
]),
+ folder('BOB Gateway', '/sdk/swidge-modules/swidge-gateway', 'Waypoints', [
+ usage('/sdk/swidge-modules/swidge-gateway/usage'),
+ configuration('/sdk/swidge-modules/swidge-gateway/configuration'),
+ apiReference('/sdk/swidge-modules/swidge-gateway/api-reference'),
+ ]),
folder('Velora', '/sdk/swap-modules/swap-velora-evm', 'ArrowLeftRight', [
usage('/sdk/swap-modules/swap-velora-evm/usage'),
guides([