Fiat Onramp

Cash App supports zero-fee Lightning payments. Orchestra combines this with its Lightning-to-stablecoin pipeline to create a fiat-to-crypto onramp with a single API call. The user pays a Lightning invoice through Cash App (debit card, no fees), and Orchestra handles the swap and delivery to any supported destination chain. The result is the cheapest onramp to USDC, ETH, SOL, or any other supported asset.

Try it live at orchestra.flashnet.xyz/onramp.

How It Works

Your app calls POST /v1/orchestration/onramp with the destination chain, asset, recipient address, and BTC amount in sats.
Orchestra creates a Lightning invoice, builds the order, and returns a Cash App deeplink.
The user opens the deeplink (or scans a QR code), pays in Cash App.
Orchestra receives the Lightning payment, swaps BTC to the destination asset, and delivers it.

The entire flow is a single API call. No separate quote and submit steps.

Why It’s Cheap

Cash App charges zero fees on Lightning payments. Orchestra charges 0.05% on the swap. There are no intermediary fees, no card processing fees, and no withdrawal fees. Compare this to traditional onramps:

Provider	Typical fee
Card-based onramps	1.5-3.5%
Bank transfer onramps	0.5-1.5%
Cash App + Orchestra	~0.05%

Cash App Limits

Cash App allows up to $999 in Lightning payments per rolling 7-day window. Limits reset at the top of the next hour after the 7-day window passes.

The onramp endpoint should not be called with amounts exceeding $999 equivalent. Validate the amount client-side before calling the API.

Supported Routes

The onramp endpoint accepts any destination that Orchestra supports from a Lightning BTC source:

lightning:BTC -> solana:USDC
lightning:BTC -> base:USDC
lightning:BTC -> base:USDT
lightning:BTC -> base:ETH
lightning:BTC -> solana:SOL
lightning:BTC -> spark:USDB
lightning:BTC -> ethereum:USDC
lightning:BTC -> arbitrum:USDC
lightning:BTC -> tron:USDT
Many more routes…

The source is always lightning:BTC. The amount is always in sats.

Integration

Get a price estimate

Use the estimate endpoint to show the user what they’ll receive before committing.

curl 'https://orchestration.flashnet.xyz/v1/orchestration/estimate?\
sourceChain=lightning&sourceAsset=BTC&\
destinationChain=solana&destinationAsset=USDC&\
amount=100000'

Response:

{
  "estimatedOut": "96543210",
  "feeAmount": "4830",
  "feeBps": 5,
  "feeAsset": "USDC"
}

Create the onramp order

A single call creates the Lightning invoice, builds the order, and returns the Cash App deeplink.

const BASE_URL = 'https://orchestration.flashnet.xyz';

const onramp = await fetch(`${BASE_URL}/v1/orchestration/onramp`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.FLASHNET_API_KEY}`,
    'X-Idempotency-Key': `onramp:${Date.now()}`,
  },
  body: JSON.stringify({
    destinationChain: 'solana',
    destinationAsset: 'USDC',
    recipientAddress: 'So1YourSolanaAddress...',
    amount: '100000', // sats
    slippageBps: 50,
  }),
}).then((r) => r.json());

Response:

{
  "orderId": "op_abc123",
  "quoteId": "q_xyz789",
  "depositAddress": "lnbc1000n1pj...",
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc1000n1pj...",
    "shortUrl": "https://orchestration.flashnet.xyz/pay/a3xKm2Rq"
  },
  "amountIn": "100000",
  "estimatedOut": "96543210",
  "feeAmount": "4830",
  "feeBps": 5,
  "totalFeeAmount": "4830",
  "feeAsset": "USDC",
  "route": [
    "verify-lightning-deposit",
    "flashnet-swap-btc-to-usdb",
    "bridge-usdb-to-usdc",
    "deliver-solana-usdc"
  ],
  "expiresAt": "2025-01-15T12:04:00.000Z"
}

Open Cash App

On mobile, redirect the user to the deeplink. On desktop, display the deeplink as a QR code for the user to scan with their phone. Use shortUrl when sharing payment links in messages or emails.

// Mobile: direct deeplink
window.location.href = onramp.paymentLinks.cashApp;

// Desktop: render QR code with the deeplink URL
// The QR encodes the full cash.app URL, not the BOLT11 invoice
renderQR(onramp.paymentLinks.cashApp);

// Sharing: use the short URL for texts, emails, etc.
const shareableLink = onramp.paymentLinks.shortUrl;
// e.g. https://orchestration.flashnet.xyz/pay/a3xKm2Rq

The Lightning invoice expires at expiresAt (2 minutes from creation). If the user doesn’t pay in time, create a new onramp order.

Track the order

Use SSE or polling to track progress. The order moves through processing -> confirming -> swapping -> bridging -> delivering -> completed.

// SSE (preferred)
const es = new EventSource(
  `${BASE_URL}/v1/sse/operations/${onramp.orderId}?token=${API_KEY}`
);
es.addEventListener('status', (e) => {
  const { status } = JSON.parse(e.data);
  console.log(status); // confirming, swapping, bridging, completed, etc.
});

// Or poll
const status = await fetch(
  `${BASE_URL}/v1/orchestration/status?id=${onramp.orderId}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then((r) => r.json());

API Reference

POST /v1/orchestration/onramp

Requires authentication (Authorization: Bearer <api_key>) and idempotency (X-Idempotency-Key). Request body:

Field	Required	Type	Notes
`destinationChain`	Yes	string	Target chain (e.g., `solana`, `base`)
`destinationAsset`	Yes	string	Target asset (e.g., `USDC`, `ETH`)
`recipientAddress`	Yes	string	Destination address on the target chain
`amount`	Yes	string	BTC amount in sats (integer string)
`slippageBps`	No	number	Slippage tolerance in basis points (default: 50)
`appFees`	No	array	Inline affiliate fees (mutually exclusive with `affiliateId`)
`affiliateId`	No	string	Registered affiliate ID (mutually exclusive with `appFees`)

Response fields:

Field	Type	Notes
`orderId`	string	Operation ID for tracking
`quoteId`	string	Underlying quote ID
`depositAddress`	string	BOLT11 Lightning invoice
`paymentLinks.cashApp`	string	Cash App deeplink URL
`paymentLinks.shortUrl`	string	Short redirect URL (302s to Cash App deeplink)
`amountIn`	string	BTC amount in sats
`estimatedOut`	string	Estimated output in destination asset smallest units
`feeAmount`	string	Platform fee
`feeBps`	number	Fee rate in basis points
`totalFeeAmount`	string	Total fees (platform + app fees)
`feeAsset`	string	Fee denomination
`route`	string[]	Pipeline steps
`expiresAt`	string	ISO timestamp when the Lightning invoice expires

Affiliate Fees

The onramp endpoint supports the same affiliate fee model as the standard quote flow. Pass either appFees (inline) or affiliateId (registered) to collect fees on each onramp transaction.

{
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "recipientAddress": "So1...",
  "amount": "100000",
  "affiliateId": "my-partner"
}

Fees are settled in USDC on the destination chain. See Affiliate Fees for registration and claim details.

Next Steps

API Overview for authentication and error handling
Order Lifecycle for status transitions and webhook payloads
Webhooks for real-time order updates

Overview

Guides

Reference

Security

How It Works

Why It’s Cheap

Cash App Limits

Supported Routes

Integration

API Reference

POST /v1/orchestration/onramp

Affiliate Fees

Next Steps

Overview

Guides

Reference

Security

​How It Works

​Why It’s Cheap

​Cash App Limits

​Supported Routes

​Integration

​API Reference

​POST /v1/orchestration/onramp

​Affiliate Fees

​Next Steps

How It Works

Why It’s Cheap

Cash App Limits

Supported Routes

Integration

API Reference

POST /v1/orchestration/onramp

Affiliate Fees

Next Steps