The payment rail that cannot freeze your money.

Beanie helps apps, merchants, bots, and agents accept stablecoin payments across supported EVM, Solana, and Sui routes without building chain-specific payment operations from scratch.

Payment Flow

What your app needs to store

Getting Started

Start with the path most products need first: give a payer a lane, keep your own product context attached, then update the customer experience when Beanie reports movement.

1. Create a merchant lane

Copycurl -X POST https://api.your-beanie-host.com/api/v1/accounts/init \
  -H 'content-type: application/json' \
  -H 'x-context-fp: checkout-or-agent-session-id' \
  -d '{
    "chain_id": "BASE",
    "source_eoa": "0x1111111111111111111111111111111111111111",
    "destination_chain": "BASE",
    "destination_eoa": "0x2222222222222222222222222222222222222222"
  }'

Response

Copy{
  "merchant_id": "mch_...",
  "api_token": "eyJ...",
  "deposit_lane_address": "0x...",
  "receiver_config_address": null,
  "deploy_nonce": 42,
  "fee_bps": 30,
  "qr_data": null,
  "status": "PENDING"
}

2. Store the token with its fingerprint

Store the returned token with the same context fingerprint used to create the lane. That pair lets your product answer the question that matters: what happened to this payment lane?

3. Subscribe to payment events

Copyconst ws = new WebSocket("wss://api.your-beanie-host.com/v1/streaming");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    api_token: apiToken,
    context_fp: contextFingerprint
  }));
});

ws.addEventListener("message", (message) => {
  const event = JSON.parse(message.data);
  console.log(event.event, event.data);
});

API Reference

These endpoints are the small surface area your product needs to create lanes, remove gas friction, verify payment state, and react to events across supported chains.

Relay methods

Sponsored relay turns gas into a product decision: your app can pay the network cost for eligible transfers while Beanie records the authorization and final result.

Test the API

Try the exact calls your integration will use. Pick the endpoint, fill only the fields that matter for that call, and send it to your local, sandbox, or deployed Beanie API.

CopySelect an endpoint and send a request.

Usage Examples

These examples are written for the real jobs your product needs to do: create a lane, read state, receive notifications, and sponsor a transfer when gas would interrupt payment.

Create a payment lane

Create a lane when a merchant, bot, customer session, or autonomous job needs an address that Beanie can track.

Copyconst baseUrl = "https://api.your-beanie-host.com";

async function createLane({
  sourceChain,
  destinationChain,
  ownerAddress,
  settlementAddress
}) {
  const contextFingerprint = crypto.randomUUID();
  const response = await fetch(`${baseUrl}/api/v1/accounts/init`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-context-fp": contextFingerprint
    },
    body: JSON.stringify({
      chain_id: sourceChain,
      destination_chain: destinationChain,
      owner_address: ownerAddress,
      source_eoa: ownerAddress,
      destination_eoa: settlementAddress,
      dst_recipient: settlementAddress
    })
  });

  const payload = await response.json();
  if (!response.ok) throw new Error(payload.error || "Lane creation failed");

  // Store merchant_id, api_token, and contextFingerprint together.
  return { ...payload, contextFingerprint };
}

Copycurl -X POST https://api.your-beanie-host.com/api/v1/accounts/init \
  -H 'content-type: application/json' \
  -H 'x-context-fp: checkout-or-agent-session-id' \
  -d '{
    "chain_id": "BASE",
    "destination_chain": "BASE",
    "owner_address": "0x1111111111111111111111111111111111111111",
    "source_eoa": "0x1111111111111111111111111111111111111111",
    "destination_eoa": "0x2222222222222222222222222222222222222222",
    "dst_recipient": "0x2222222222222222222222222222222222222222"
  }'

Read balance and history

Use the token returned by lane creation to read merchant state. Most products call this from their backend or protected dashboard.

Copyasync function readMerchantState({ merchantId, apiToken, contextFingerprint, chainId = "BASE" }) {
  const headers = {
    authorization: `Bearer ${apiToken}`,
    "x-context-fp": contextFingerprint
  };
  const historyQuery = `chain_id=${encodeURIComponent(chainId)}&limit=30&offset=0`;

  const [balanceResponse, historyResponse] = await Promise.all([
    fetch(`${baseUrl}/api/v1/accounts/${merchantId}/balance?chain_id=${chainId}`, { headers }),
    fetch(`${baseUrl}/api/v1/accounts/${merchantId}/transactions?${historyQuery}`, { headers })
  ]);

  if (!balanceResponse.ok) throw new Error("Balance unavailable");
  if (!historyResponse.ok) throw new Error("History unavailable");

  return {
    balance: await balanceResponse.json(),
    transactions: await historyResponse.json()
  };
}

Copycurl 'https://api.your-beanie-host.com/api/v1/accounts/mch_example/transactions?chain_id=BASE&limit=30&offset=0' \
  -H "authorization: Bearer $BEANIE_API_TOKEN" \
  -H "x-context-fp: $BEANIE_CONTEXT_FP"

Subscribe to notifications

Use the WebSocket stream to keep checkout screens, merchant dashboards, bots, and agents synchronized without polling.

Copyconst socket = new WebSocket("wss://api.your-beanie-host.com/v1/streaming");

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    action: "subscribe",
    api_token: apiToken,
    context_fp: contextFingerprint
  }));
});

socket.addEventListener("message", (message) => {
  const payload = JSON.parse(message.data);

  if (payload.event === "deposit_detected") {
    markOrderPending(payload.data);
  }

  if (payload.event === "sweep_completed" || payload.event === "relay_completed") {
    markOrderPaid(payload.data);
  }

  if (payload.event === "relay_failed") {
    showRetry(payload.data);
  }
});

Solana sponsored transfer

Ask Beanie to prepare the transaction, let the wallet sign it, then queue the signed authorization. The final result arrives through history reads and streaming events.

Copyasync function sponsorSolanaTransfer({
  merchantId,
  fromAddress,
  toAddress,
  value,
  provider
}) {
  const preparedResponse = await fetch(`${baseUrl}/api/v1/relay/solana/prepare`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      merchant_id: merchantId,
      chain_id: "SOLANA-MAIN",
      direction: "outbound",
      from_address: fromAddress,
      to_address: toAddress,
      value
    })
  });
  const prepared = await preparedResponse.json();
  if (!preparedResponse.ok) throw new Error(prepared.error || "Solana relay unavailable");

  const transaction = solanaWeb3.Transaction.from(
    Uint8Array.from(atob(prepared.base64_transaction), (char) => char.charCodeAt(0))
  );
  const signed = await provider.signTransaction(transaction);
  const signedBytes = signed.serialize({
    requireAllSignatures: false,
    verifySignatures: false
  });

  return fetch(`${baseUrl}/api/v1/relay/authorize`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      relay_method: prepared.relay_method || "CO-SIGN",
      merchant_id: merchantId,
      chain_id: prepared.chain_id || "SOLANA-MAIN",
      from_address: prepared.from_address,
      to_address: prepared.to_address,
      value: prepared.value,
      nonce: prepared.nonce,
      base64_transaction: btoa(String.fromCharCode(...signedBytes))
    })
  });
}

Copycurl -X POST https://api.your-beanie-host.com/api/v1/relay/solana/prepare \
  -H 'content-type: application/json' \
  -d '{
    "merchant_id": "mch_example",
    "chain_id": "SOLANA-MAIN",
    "direction": "outbound",
    "from_address": "11111111111111111111111111111111",
    "to_address": "11111111111111111111111111111111",
    "value": "1000000"
  }'

EVM gasless transfer

For EVM chains, the user signs typed data. Beanie receives the signature parts and queues the relay.

Copyasync function authorizeEvmTransfer({
  merchantId,
  fromAddress,
  toAddress,
  value,
  chainId,
  usdcAddress,
  ethereum
}) {
  const validAfter = Math.floor(Date.now() / 1000);
  const validBefore = validAfter + 300;
  const nonce = crypto.getRandomValues(new Uint8Array(32));
  const hexNonce = `0x${[...nonce].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;

  const typedData = {
    types: {
      EIP712Domain: [
        { name: "name", type: "string" },
        { name: "version", type: "string" },
        { name: "chainId", type: "uint256" },
        { name: "verifyingContract", type: "address" }
      ],
      TransferWithAuthorization: [
        { name: "from", type: "address" },
        { name: "to", type: "address" },
        { name: "value", type: "uint256" },
        { name: "validAfter", type: "uint256" },
        { name: "validBefore", type: "uint256" },
        { name: "nonce", type: "bytes32" }
      ]
    },
    primaryType: "TransferWithAuthorization",
    domain: {
      name: "USD Coin",
      version: "2",
      chainId,
      verifyingContract: usdcAddress
    },
    message: {
      from: fromAddress,
      to: toAddress,
      value,
      validAfter,
      validBefore,
      nonce: hexNonce
    }
  };

  const signature = await ethereum.request({
    method: "eth_signTypedData_v4",
    params: [fromAddress, JSON.stringify(typedData)]
  });
  const { v, r, s } = splitEvmSignature(signature);

  return fetch(`${baseUrl}/api/v1/relay/authorize`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      relay_method: "TWA",
      merchant_id: merchantId,
      chain_id: "BASE",
      from_address: fromAddress,
      to_address: toAddress,
      value,
      valid_after: validAfter,
      valid_before: validBefore,
      nonce: hexNonce,
      v,
      r,
      s
    })
  });
}

Copycurl -X POST https://api.your-beanie-host.com/api/v1/relay/authorize \
  -H 'content-type: application/json' \
  -d '{
    "relay_method": "TWA",
    "merchant_id": "mch_example",
    "chain_id": "BASE",
    "from_address": "0x1111111111111111111111111111111111111111",
    "to_address": "0x2222222222222222222222222222222222222222",
    "value": "10.000000",
    "valid_after": 1710000000,
    "valid_before": 1710000300,
    "nonce": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "v": 27,
    "r": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "s": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  }'

Sui sponsored transfer

For Sui, the wallet builds and signs the PTB, then Beanie submits the signed bytes through the sponsored relay path.

Copyasync function authorizeSuiTransfer({
  merchantId,
  fromAddress,
  toAddress,
  value,
  nonce,
  txBytes,
  signatures
}) {
  const response = await fetch(`${baseUrl}/api/v1/relay/authorize`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      relay_method: "SUI-SPONSORED",
      merchant_id: merchantId,
      chain_id: "SUI-MAIN",
      from_address: fromAddress,
      to_address: toAddress,
      value,
      nonce,
      tx_bytes: txBytes,
      signatures
    })
  });
  const payload = await response.json();
  if (!response.ok) throw new Error(payload.error || "Sui relay unavailable");
  return payload;
}

Copycurl -X POST https://api.your-beanie-host.com/api/v1/relay/authorize \
  -H 'content-type: application/json' \
  -d '{
    "relay_method": "SUI-SPONSORED",
    "merchant_id": "mch_example",
    "chain_id": "SUI-MAIN",
    "from_address": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "to_address": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "value": "10.000000",
    "nonce": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "tx_bytes": "AA==",
    "signatures": ["AA=="]
  }'

Realtime Events

Use streaming events when polling would make the product feel late. Beanie pushes merchant-scoped payment and relay updates so your UI, bots, and backend jobs can move with the payment.

Subscribe frame

Copy{
  "action": "subscribe",
  "api_token": "eyJ...",
  "context_fp": "checkout-or-agent-session-id"
}

Event envelope

Copy{
  "event": "relay_completed",
  "data": {
    "chain_id": "BASE",
    "relay_tx_hash": "0xabc...",
    "value": "10.000000",
    "status": "CONFIRMED"
  },
  "merchant_id": "mch_example"
}

Contracts & Addresses

Use these onchain addresses to verify token, program, and relay assumptions across supported chains before moving value through a Beanie integration.

Public token and program addresses

Beanie lane addresses

Supported Chains

Beanie is built for multichain payment acceptance. Use canonical labels in production code and aliases only where your deployment explicitly supports them.

Chain aliases

FAQ