NimFuel

Use NIM to cover Polygon gas for a USDT action in Nimiq Pay.

Open NimFuel · Read the docs · Watch the 30-second launch video

NimFuel helps a Nimiq Pay user send Polygon USDT when their wallet has USDT but no POL for gas. The user chooses the recipient and amount, approves the exact USDT action in their wallet, pays the displayed NIM amount, and NimFuel verifies that payment before its relayer spends POL to submit the already-authorized transfer.

The user keeps control of the USDT action. NimFuel never asks for a seed phrase or private key.

A Polygon USDT transfer needs POL for gas. First-time Nimiq Pay users may have USDT in their Polygon wallet without holding POL, which leaves a valid transfer blocked at the final step.

NimFuel gives that user one clear path:

1. Check the connected Nimiq Pay and Polygon wallet.
2. Choose a recipient and any USDT amount accepted by the live service policy.
3. Approve the exact USDT authorization in Nimiq Pay.
4. Pay the live NIM quote using an order-specific reference.
5. Let NimFuel verify the NIM payment, relay with POL, and verify the Polygon receipt.

flowchart LR
    A[Nimiq Pay user] -->|Chooses recipient and USDT amount| B[NimFuel app]
    B -->|Reads wallet and prepares signed authorization| C[NimFuel API]
    C -->|Reads live fee and token state| D[Polygon]
    C -->|Returns an exact NIM quote| B
    B -->|Pays NIM with an order reference| E[Nimiq]
    E -->|Independent payment verification| C
    C -->|Pays gas with relayer POL and submits authorized USDT transfer| D
    D -->|Receipt and transfer result| C
    C -->|Fulfilled order and history| B

The order follows a deliberate verification sequence:

sequenceDiagram
    participant U as User in Nimiq Pay
    participant A as NimFuel app
    participant S as NimFuel API
    participant N as Nimiq verification rail
    participant P as Polygon

    U->>A: Enter recipient and USDT amount
    A->>U: Request USDT authorization
    U-->>A: Signed authorization
    A->>S: Preflight signed action
    S->>P: Read nonce, USDT state, and gas conditions
    S-->>A: Live NIM quote
    A->>U: Create and pay NIM order
    U->>N: Send NIM with order reference
    S->>N: Verify recipient, amount, reference, and inclusion
    N-->>S: Payment confirmed
    S->>P: Relay the authorized USDT action with POL
    P-->>S: Transaction receipt
    S-->>A: Fulfilled order and receipt link

The verified-proof page records a completed live Polygon USDT relay. It is evidence for that recorded transaction, not a blanket guarantee that every future transaction will succeed.

• The relayer private key stays on the server and never reaches the browser.
• The wallet signs the recipient, amount, token, chain context, and nonce. The server additionally rejects authorizations past their deadline; the token's meta-transaction format does not include a deadline, so a signed authorization stays valid on-chain until its nonce is used.
• NimFuel verifies the NIM payment against the exact order before Polygon fulfillment is unlocked.
• Relay attempts and recovery states are durable. A retry stays attached to the same paid order and requires a fresh authorization when needed.
• Orders and history are scoped to the connected Polygon address. Loading history requires a short-lived wallet signature (EIP-191) proving ownership of that address.
• Rate limits key on the socket address; set NIMFUEL_TRUST_PROXY=true only behind a proxy that appends X-Forwarded-For (enabled automatically on Render).

Read SECURITY.md for the reporting process and operational boundaries.

Requirements: Node.js 20.19 or newer, a Nimiq Pay-compatible wallet context, and local environment values.

cd server
npm ci

cd ../app
npm ci

Create app/.env.local and server/.env using the variable names in .env.example. Keep all real credentials local. The relayer private key and database URL belong only in server/.env or the deployment provider's secret store.

Run the API and app in separate terminals:

cd server
npm run dev

cd app
npm run dev -- --host 0.0.0.0

The development app expects the API at http://localhost:3001.

npm --prefix app run build
npm --prefix server run build
npm --prefix server run test:quote
npm --prefix server run test:durable
npm --prefix server run test:stage2

These checks verify the local checkout. They do not replace a live wallet approval, independent NIM payment verification, or a confirmed Polygon receipt.

NimFuel currently supports the Polygon USDT flow shown here. It is not a wallet, bridge, swap service, or a general-purpose asset transfer layer. Broader onboarding, DEX, and multi-chain ideas remain future work until they have their own tested integration and recovery model.

MIT. See LICENSE.