Gas Station

2FA-gated faucet that funds fresh machine wallets on peaq chain so they can pay the gas for activation.

Gas Station is a 2FA-gated faucet that funds fresh machine wallets on peaq chain so they can pay the gas for activation.

Why Gas Station exists

A newly generated machine keypair has zero balance. Before it can activate (which bonds PEAQ on a subscription tier under Economics 2.0, or 1 PEAQ under Tokenomics 1.0), it needs native tokens for gas. Gas Station solves this bootstrap problem: the owner enrolls in 2FA once, then funds each machine wallet with a single SDK call. Gas Station funds peaq wallets only. The Solana owner wallet of a machine homed on Solana needs SOL for fees and rent, which you fund yourself (Solana onboarding).

2FA setup flow

1. Initiate 2FA enrollment

   Call setupFaucet2FA with the owner’s address. The faucet returns an otpauthUri for manual entry and a qrImageUrl for scanning.

   JS/TS

   const setup = await client.setupFaucet2FA(
     ownerAddress,
     "https://depinstation.peaq.xyz"
   );
   console.log(setup);
   // setup.otpauthUri  : paste into authenticator app
   // setup.qrImageUrl  : render immediately, expires in ~2 minutes
   
2. Scan QR code with authenticator app

   Open any TOTP-compatible authenticator (Google Authenticator, Authy, 1Password). Scan the QR code or manually enter the otpauthUri. The QR image expires after approximately 2 minutes.

3. Confirm 2FA activation

   Submit the current TOTP code from the authenticator app to activate 2FA for this owner address.

   JS/TS

   await client.confirmFaucet2FA(
     ownerAddress,
     "https://depinstation.peaq.xyz",
     "123456" // TOTP code from authenticator
   );
   

Funding a machine wallet

After 2FA is active, fund any machine wallet with fundFromGasStation. The response is a discriminated union: either success (transfer landed) or skipped (wallet already funded).

JS/TS

const result = await client.fundFromGasStation(
  {
    ownerAddress: "0xOwner...",
    targetWalletAddress: machineAddress,
    chainId: "peaq",
    twoFactorCode: "654321",
  },
  "https://depinstation.peaq.xyz"
);

if (result.status === "success") {
  console.log("Funded:", result.txHash, result.fundedAmount);
} else {
  // status === "skipped"
  console.log("Already funded:", result.currentBalance);
}

Success response

Field (JS / Python)	Type	Description
status	"success"	Transfer completed
txHash / tx_hash	0x-prefixed hex	Transaction hash of the funding transfer
fundedAmount / funded_amount	string (decimal wei)	Amount transferred
requestId (JS only)	string	Idempotency key, echoed from the request or generated by the SDK

Skipped response

Field (JS / Python)	Type	Description
status	"skipped"	Wallet already has sufficient balance
currentBalance / current_balance	string (decimal wei)	Target wallet’s current balance
minGasBalance / min_gas_balance	string (decimal wei)	Faucet-configured minimum threshold
requestId (JS only)	string	Idempotency key

The Python SDK does not return the idempotency key. If you need it for retry recovery, pass request_id in explicitly and hold the value yourself.

Rate limits and caps

Gas Station enforces three independent throttles to prevent abuse, plus a per-chain minimum balance threshold that decides whether a funding request transfers anything at all. The cap values, rate-limit windows, and minimum gas balance are configured server-side, so branch on the error codes and the skipped status rather than hard-coding numbers.

Limit	Scope	Surfaces as	Description
Rate limit	Per owner	RATE_LIMITED	Too many funding requests within the faucet’s hourly window. Back off and retry.
Daily funding cap	Per owner	CAP_EXCEEDED_OWNER	Total funded amount per owner per day.
Daily funding cap	Per wallet	CAP_EXCEEDED_WALLET	Total funded amount per target wallet per day.
Minimum gas balance	Per chain	skipped response	When the target wallet already holds at least this much, the faucet returns skipped with currentBalance/current_balance and minGasBalance/min_gas_balance instead of transferring.

Error codes

Gas Station defines 20 error codes. Not every endpoint can raise every code; the subset depends on what the endpoint actually does. The three endpoints are POST /2fa/setup (setupFaucet2FA / setup_faucet_2fa), POST /2fa/confirm (confirmFaucet2FA / confirm_faucet_2fa), and POST /faucet/fund (fundFromGasStation / fund_from_gas_station).

Code	Endpoints	Meaning
INVALID_OWNER_ADDRESS	setup, fund	Owner address failed server-side format validation.
INVALID_TARGET_ADDRESS	fund	Malformed targetWalletAddress.
INVALID_CHAIN_ID	fund	Unsupported chainId.
INVALID_REQUEST_ID	fund	The supplied requestId was not a valid UUID.
INVALID_PAYLOAD	setup, fund	Request body did not match the spec (e.g. unknown format).
QR_GENERATION_FAILED	setup	The faucet failed to render the QR image.
QR_NOT_FOUND	fund	QR token does not exist (rare; surfaces when a stale QR is referenced).
QR_EXPIRED	fund	QR token has expired.
INVALID_2FA	confirm, fund	TOTP code did not match the secret.
2FA_NOT_CONFIGURED	confirm, fund	Owner never completed setup. Call setupFaucet2FA first.
2FA_NOT_ACTIVE	fund	Setup done but never confirmed. Call confirmFaucet2FA first.
2FA_LOCKED	confirm, fund	Owner locked after too many invalid attempts.
DUPLICATE_REQUEST	fund	A request with this requestId is still in flight.
REQUEST_ALREADY_PROCESSED	fund	This requestId has already completed.
RATE_LIMITED	fund	Faucet rate limit exceeded.
CAP_EXCEEDED_OWNER	fund	Owner daily funding cap exceeded.
CAP_EXCEEDED_WALLET	fund	Wallet daily funding cap exceeded.
TRANSFER_FAILED	fund	On-chain transfer failed.
CHAIN_RPC_ERROR	fund	Faucet’s upstream RPC provider failed.
INTERNAL_ERROR	setup, confirm, fund	Unhandled server-side failure. The JS SDK also raises this code locally for non-JSON bodies and unexpected envelope shapes.

For SDK-owned message strings and HTTP status codes per code, see errors.

Cross-links

• JS SDK faucet methods documents setupFaucet2FA, confirmFaucet2FA, and fundFromGasStation
• Python SDK faucet methods documents the Python equivalents
• Self-managed onboarding guide shows Gas Station in the full registration flow