Faucet API: Claim Testnet Funds on the Sundial L2

The faucet API lets you claim test funds on the Sundial L2 programmatically, making it straightforward to fund addresses in automated test suites, CI pipelines, and integration scripts. Supply a testnet address and your bearer token, and the faucet builds an L2 transfer from its own wallet and inserts it into the node’s mempool. All tokens dispensed by the faucet are testnet-only and carry no real-world value.

The faucet is a testnet-only, server-to-server endpoint protected by a bearer token. Claims are subject to per-address and per-IP cooldowns to prevent abuse. Do not rely on the faucet for high-frequency automated funding — pre-fund a set of test wallets at the start of a test run instead.

POST /faucet/claims — Claim Testnet L2 Funds

Submit a claim request for test funds on the Sundial L2. The faucet validates the address, checks cooldown and IP limits, builds and signs an L2 transfer, validates it with the node’s own rule engine, and returns the transaction hash once the transfer is accepted into the mempool.

Request

POST /faucet/claims
Authorization: Bearer <FAUCET_API_KEY>
Content-Type: application/json

Request Body

{
  "address": "addr_test1qp...",
  "idempotencyKey": "my-test-run-001",
  "ipHash": "<hashed-ip>"
}

string

required

Bech32 address to receive the funds on the L2. Must start with addr_test1, must carry a valid payment credential, must not be a script address, and must match the node’s network.

string

required

A unique string identifying this claim request. Resending the same idempotencyKey for the same address is safe — the faucet returns the original result rather than triggering a second transaction. Use a value that is stable across retries, such as a test run ID or a UUID generated at the start of your pipeline.

string

required

A non-empty string representing the requester’s IP address (typically a hash). Used for per-IP daily rate limiting. When integrating through the Sundial web frontend, the proxy populates this field automatically. When calling the API directly, pass a consistent identifier for the originating IP.

Example

curl -X POST https://rpc.testnet.sundialprotocol.com/faucet/claims \
  -H "Authorization: Bearer <FAUCET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "addr_test1qp...",
    "idempotencyKey": "my-test-run-001",
    "ipHash": "a1b2c3d4e5f6..."
  }'

const response = await fetch(
  "https://rpc.testnet.sundialprotocol.com/faucet/claims",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.FAUCET_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      address: "addr_test1qp...",
      idempotencyKey: `test-run-${Date.now()}`,
      ipHash: "a1b2c3d4e5f6...",
    }),
  }
);

if (!response.ok) {
  const { error, code } = await response.json();
  console.error(`Faucet claim failed [${code}]: ${error}`);
} else {
  const { claimId, txHash, amount, nextEligibleAt } = await response.json();
  console.log(`Funded! L2 txHash=${txHash}, amount=${amount} lovelace`);
  console.log(`Next claim eligible at: ${nextEligibleAt}`);
}

Success Response

{
  "claimId": "3f2a1b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "txHash": "9e4f3a2b1c0d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f",
  "amount": "100000000",
  "nextEligibleAt": "2025-01-15T14:30:00.000Z"
}

string

UUID uniquely identifying this claim record. Use this for support requests if a claim fails to arrive.

string

Hex-encoded hash of the L2 funding transaction. It is not an L1 transaction, so L1 block explorers won’t show it. Look it up with GET /tx on the node.

string

Lovelace amount dispensed, returned as a string to preserve full integer precision.

string

ISO 8601 timestamp indicating when this address becomes eligible for another claim. Store this value to avoid unnecessary cooldown errors in subsequent requests.

Error Responses

Claim failures return an object with a stable code field alongside a human-readable error string. Handle these by code rather than by HTTP status or message text. Three failures happen before a claim is processed and carry no code; see Errors without a code.

`code`	HTTP Status	Description
`DISABLED`	404	The faucet is not enabled on this node. The response is deliberately indistinguishable from a missing route.
`ADDRESS_INVALID`	400	The `address` field failed to parse as a valid bech32 address.
`ADDRESS_NETWORK_MISMATCH`	400	The address is valid but belongs to the wrong network (e.g. a mainnet address on a testnet node).
`ADDRESS_NO_PAYMENT_CREDENTIAL`	400	The address has no payment credential (e.g. a bare stake address).
`ADDRESS_SCRIPT`	400	The address is a script address — the faucet only funds wallet addresses.
`COOLDOWN`	429	This address claimed too recently. The response body includes `nextEligibleAt`.
`IP_LIMIT`	429	The daily per-IP claim cap has been reached. Try again tomorrow or use a different network path.
`DEPLETED`	503	The faucet wallet has insufficient funds. This is a temporary condition — check back later or use the web UI for status.
`VALIDATION_FAILED`	500	The funding transfer was not accepted into the mempool. This is a server-side error — retry after a brief delay.
`INTERNAL`	500	An unexpected internal error occurred.

Error Response Shape

{
  "error": "Human-readable description",
  "code": "COOLDOWN",
  "nextEligibleAt": "2025-01-15T14:30:00.000Z"
}

The nextEligibleAt field is only present for COOLDOWN responses. For 5xx codes (DEPLETED, VALIDATION_FAILED, INTERNAL), the error string is always "Faucet request failed". The detail is in the node’s logs.

Errors without a code

HTTP Status	Body	When
401	`{ "error": "Unauthorized" }`	The bearer token is missing or wrong.
400	`{ "error": "Request body must be a JSON object" }`	The body isn’t valid JSON, or isn’t an object.
400	`{ "error": "Request body must contain non-empty 'address', 'idempotencyKey' and 'ipHash' strings" }`	A required field is missing or empty.
404	`{ "error": "Faucet is not enabled" }`	The faucet is switched off, or no API key is configured.

Error Handling Example

async function claimFaucet(address: string, runId: string, ipHash: string): Promise<void> {
  const res = await fetch(
    "https://rpc.testnet.sundialprotocol.com/faucet/claims",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.FAUCET_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ address, idempotencyKey: runId, ipHash }),
    }
  );

  if (res.ok) {
    const { txHash, amount } = await res.json();
    console.log(`Claimed ${amount} lovelace → ${txHash}`);
    return;
  }

  const { code, error, nextEligibleAt } = await res.json();

  switch (code) {
    case "COOLDOWN":
      console.warn(`Address on cooldown until ${nextEligibleAt}`);
      break;
    case "IP_LIMIT":
      console.warn("Daily IP limit reached — try again tomorrow");
      break;
    case "DEPLETED":
      console.warn("Faucet temporarily empty — check sundialprotocol.com/testnet/faucet");
      break;
    case "ADDRESS_NETWORK_MISMATCH":
      throw new Error(`Wrong network — use an addr_test1 address for testnet`);
    default:
      throw new Error(`Faucet error [${code}]: ${error}`);
  }
}

Idempotency and Retry Behaviour

Using a stable idempotencyKey makes the faucet safe to call multiple times in retry loops without risk of double-funding:

Generate a stable key

Create an idempotency key that is unique to this logical claim but stable across retries. A test run ID, a UUID generated once at startup, or a hash of address + testRunId all work well.

Call the faucet

POST the claim with your bearer token. On a 200 response, store nextEligibleAt and proceed with your test.

Retry on transient failures

On VALIDATION_FAILED or INTERNAL errors, retry with the same idempotencyKey. The faucet deduplicates by key, so even if the first attempt partially succeeded, the retry will either return the original result or trigger a fresh transaction safely.

Respect cooldown signals

On a COOLDOWN response, wait until nextEligibleAt before retrying. On IP_LIMIT, avoid retrying from the same IP for 24 hours.

Web UI Alternative

If you prefer to claim tokens manually rather than programmatically, use the testnet faucet web interface at: https://sundialprotocol.com/testnet/faucet The web UI provides the same tokens as the API and shows your current cooldown status and estimated next eligible claim time.

The faucet dispenses test funds on the Sundial L2, from a wallet funded in the L2’s genesis state. They are used for testing L2 transactions and covering their fees. They have no monetary value and don’t exist on the settlement L1.

Node API

SDKs

Operator reference

Protocol reference

Faucet API: Claim Testnet Funds on the Sundial L2

POST /faucet/claims — Claim Testnet L2 Funds

Request

Request Body

Example

Success Response

Error Responses

Error Response Shape

Errors without a code

Error Handling Example

Idempotency and Retry Behaviour

Web UI Alternative

​POST /faucet/claims — Claim Testnet L2 Funds

​Request

​Request Body

​Example

​Success Response

​Error Responses

​Error Response Shape

​Errors without a code

​Error Handling Example

​Idempotency and Retry Behaviour

​Web UI Alternative

POST /faucet/claims — Claim Testnet L2 Funds

Request

Request Body

Example

Success Response

Error Responses

Error Response Shape

Errors without a code

Error Handling Example

Idempotency and Retry Behaviour

Web UI Alternative