Developers

Check a wallet

Every rule of every live pool, evaluated for one address. Nothing is reserved by reading it.

curl /api/v1/wallets/0xYourWallet/eligibility

Each pool returns eligible, the amountWei it would send, nextAvailableAt when a cooldown applies, and a checks list with a plain-language detail for each rule.

Sign in

1. POST /api/v1/auth/nonce returns a single-use nonce, valid for 10 minutes.
2. Build an EIP-4361 message for domain your ELYFUEL host and chain 99801 with that nonce, and have the wallet sign it with personal_sign. Smart-contract wallets are verified with ERC-1271.
3. POST /api/v1/auth/verify with { message, signature } returns { token, address, expiresAt }. Send it as Authorization: Bearer <token>. Sessions last 12 hours.

Signing in proves control of an address. It grants no spending permission and cannot move funds.

Fund a pool

There is no contract. A pool is funded by a plain HYPE transfer to the disclosed treasury, with the pool’s reference as transaction data:

data = hex("elyfuel:" + depositRef)   // e.g. elyfuel:3fa91c02be

Register the hash with POST /api/v1/deposits. The deposit shows as pending at once and is credited when its block is enough blocks deep. Transfers without a reference are held as unattributed until an operator assigns them. Funds are custodial from the moment they arrive.

Live events

A server-sent event stream of committed facts only: a payout appears as sponsorship.confirmed after 20 confirmations, never earlier.

const es = new EventSource('/api/v1/events/stream')
es.addEventListener('fuel', (m) => console.log(JSON.parse(m.data)))
// reconnects resume from Last-Event-ID automatically

Event types: project.registered, deposit.detected, deposit.confirmed, deposit.unattributed, sponsorship.requested, sponsorship.approved, sponsorship.rejected, sponsorship.submitted, sponsorship.confirmed, sponsorship.failed, withdrawal.requested, withdrawal.confirmed, campaign.status.

Webhooks

Project owners can register HTTPS endpoints in Fuel Pools. Each delivery is a POST with these headers, retried with exponential backoff up to 8 times:

x-elyfuel-event:      sponsorship.confirmed
x-elyfuel-delivery:   1842
x-elyfuel-timestamp:  1731150000
x-elyfuel-signature:  sha256=<hex HMAC-SHA256 of "${timestamp}.${rawBody}">

Verify before trusting the body, and reject stale timestamps:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, headers, rawBody) {
  const ts = headers['x-elyfuel-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const want = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex')
  const got = String(headers['x-elyfuel-signature'] ?? '')
  return got.length === want.length && timingSafeEqual(Buffer.from(got), Buffer.from(want))
}

Deliveries can repeat. Deduplicate on x-elyfuel-delivery.

Errors and limits

Errors return { error: { code, message } } with a matching HTTP status. Eligibility failures also include checks. Lists take limit (max 100) and offset.

Rate limits are per IP: 300 requests a minute overall, lower on writes (10 a minute for fuel requests). Limited responses return 429 with a retry-after header.

Fuel requests are idempotent per wallet and idempotencyKey: retrying a request returns the original, and a wallet can hold only one open request per pool. A retry never pays twice.

What ELYFUEL does not promise

• It is custodial, not trustless. Pool funds sit in one ELYFUEL-controlled wallet and every payout is signed by ELYFUEL.
• Eligibility rules raise the cost of abuse. They cannot prove one person per wallet, so a determined farmer with many funded wallets can still claim. Use allowlists and review for anything valuable.
• Network signals such as IP addresses are stored only as salted hashes and used for review, never published.

API reference