Traders: how leasing works

What a lease buys

A lease on the 2QUIC Marketplace is a time-bounded right to complete QUIC handshakes under a validator's staked identity. During your lease window, your client connects to the validator's TEE (an AWS Nitro Enclave holding the validator identity key), which signs the TLS 1.3 CertificateVerify of your QUIC handshake. Solana leaders then see your connection as coming from that staked validator and grant it SWQoS treatment: a reserved stream budget instead of the unstaked free-for-all.

The identity key never leaves the enclave, and the TEE is only invoked at handshake time. Once a connection is warm, sending transactions requires no further TEE calls.

Measured impact (May 2026 mainnet A/B, stake-backed vs unstaked connections):

See Methodology for how these numbers were measured.

Exclusive vs shared leases

Every lease has a mode, chosen at booking:

The honest trade-off: the handshake quota split is enforced per lease by the validator's host-proxy, but post-handshake stream bandwidth is allocated by the Solana leader to the validator's stake as a whole. That residual dilution across co-tenants cannot be metered per trader. It is exactly what the shared discount pays for. Choose exclusive if you need guaranteed, sole-tenant bandwidth.

Admission is enforced in the database. An exclusive booking needs the whole epoch range free of any other lease, and a shared booking needs no overlapping exclusive lease plus a free seat. Conflicts come back as distinct errors: 409 lease-slot-taken (with the conflicting lease id) versus 409 shared-capacity-full (all seats taken). Requesting a shared lease on a validator that does not offer it returns 422 shared-not-offered.

Epochs are the billing unit

A lease covers whole Solana epochs, from epoch_start to epoch_end inclusive. One epoch is 432,000 slots at ~0.4s per slot, roughly 2 days. A single lease spans 1 to 30 epochs (about 2 months at the top end), and an active lease can later be extended in place up to the same 30-epoch total cap.

Validator prices are quoted per epoch. The price, the platform fee, and the validator payout wallet are frozen onto your lease at booking, so later price changes never affect what you pay, including extensions.

The journey in six steps

1. Browse

Explore validators at /validators in the app, or via the public API:

curl "https://api.swqos.dev/v1/validators?available_now=true&limit=20"

The listing carries each validator's identity, region, tier, exclusive price, shared price and seat cap (when shared is offered), current stake, 30-day uptime, and reputation score. The detail endpoint GET /v1/validators/{id} adds a 64-epoch availability calendar (enough to cover any 30-epoch booking window), next_available_epoch, and effectiveness metrics (leader time per epoch, stake percentile).

2. Book

Booking is epoch-based, not slot-based. In the app, open a validator from /validators and hit its Book button, which takes you to /book/{validatorId}. From the API, POST /v1/leases with a required Idempotency-Key header (a 26-char ULID):

{
  "validator_id": "01J9X2K3M4N5P6Q7R8S9T0V1W2",
  "epoch_start": 812,
  "epoch_count": 5,
  "mode": "exclusive"
}

The 201 response contains the lease_id and a payment object with the solana_pay_url, the exact amount_lamports, and a unique memo. See Booking for the full request, response, and error catalogue.

3. Pay

Payment is a non-custodial Solana Pay transaction request. Your wallet fetches a server-built transaction containing two transfers in one atomic signature: the validator's share to its payout wallet and the platform fee (10% by default) to the platform wallet, tagged with the lease memo. Scan the QR or open the deep link, sign, done. The settlement worker confirms both legs on-chain at finalized commitment and flips the lease to active, typically seconds after finality.

4. Reveal credentials

Once the lease is active, call POST /v1/leases/{id}/credentials. This is a one-shot reveal returning the tee_endpoint_url, your per-lease api_token (shown in cleartext exactly once, the server keeps only a hash), and the TLS CA certificate. A second call returns 404 credentials-already-shown. If you lose the token, rotate it with POST /v1/leases/{id}/api-keys, which revokes the old token immediately.

This per-lease API token is the Bearer credential your bot uses for all subsequent API calls.

5. Integrate

Mint a short-lived signing JWT with POST /v1/leases/{id}/token (ES256, 10-minute TTL by default, refresh at exp - 60s), then hand it to an SDK that performs the TEE-delegated handshake and routes transactions to leaders:

• TypeScript: @swqos/staked-quic-sdk
• Rust: staked-quic-tpu-client and the signer client SDK
• Python: staked-quic-sdk

The integration guide walks the whole path with runnable snippets.

6. Manage

Your leases live on the trader dashboard at /trader in the app, or via GET /v1/leases and GET /v1/payments. From there you can:

• Extend in place: POST /v1/leases/{id}/extend bumps the window at your frozen booking price, keeping the same lease id, credentials, and API token. The total span is capped at 30 epochs.
• Rate the validator: 1 to 5 stars, once the window has elapsed and your lease shows real signing volume.
• Toggle auto-renew: a flag on the lease. Since payment is non-custodial, no automatic charge happens, the flag records your intent.

Lease lifecycle

There is no trader-initiated cancellation: once paid, a lease is committed. If a validator or the platform revokes an active lease, you receive a prorated refund of the remaining epochs, paid manually within about 24 hours.

What the marketplace never sees

The marketplace is an auth and billing layer. It is never on your data path. Your transactions flow directly from your SDK through the validator's TEE endpoint to Solana leaders. Neither the marketplace nor the validator can see your transaction content, the programs you touch, or your P&L. The validator sees handshake metadata only (who connected, when, from which IP, and signing volume), and the SDKs push no telemetry back to the marketplace.

Next steps

Ready to book? Start with Booking a lease, then follow the integration guide to get your first transaction confirmed.