# drip.0tx.io

> Agent-only Solana devnet faucet. You pay $0.01 in **mainnet** USDC via x402; we send 0.1 **devnet** SOL to the devnet wallet address you give us. A faucet that actually drips.

**Devnet only.** The SOL you receive is devnet SOL: it has no value and does not exist on mainnet. Send the devnet wallet address you want funded in `devnet_address`. A request without `devnet_address` is rejected with 400 `missing_devnet_address`.

The $0.01 is a sybil gate, not a business. There is no free tier, no account, no API key.

## Get devnet SOL

POST https://drip.0tx.io/v1/sol
Content-Type: application/json

{"devnet_address": "<devnet wallet address to fund>"}

- Every drip is exactly 0.1 SOL. `sol` is optional; if you send it, it must be 0.1.
- First call returns HTTP 402 with a `PAYMENT-REQUIRED` header (x402 V2, scheme `exact`, network `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, asset USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`). The facilitator pays the network fee; you only need USDC.
- Retry the same request with a `PAYMENT-SIGNATURE` header. Any x402 V2 client does this for you.

Easiest path (TypeScript), with a mainnet wallet holding a little USDC. `SOLANA_PRIVATE_KEY` is that wallet's 64-byte secret key in base58 (the format Phantom and Solflare export).

```sh
npm install @x402/fetch @x402/svm @solana/kit
```

```ts
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit";

const signer = await createKeyPairSignerFromBytes(getBase58Encoder().encode(process.env.SOLANA_PRIVATE_KEY!));
const client = new x402Client().register("solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", new ExactSvmScheme(signer));
const pay = wrapFetchWithPayment(fetch, client);

const res = await pay("https://drip.0tx.io/v1/sol", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ devnet_address: "<devnet wallet address>" }),
});
console.log(res.status, await res.json());
```

## Success (200)

{"sol": 0.1, "network": "devnet", "devnet_address": "...", "devnet_tx": "<sig>", "explorer": "https://explorer.solana.com/tx/<sig>?cluster=devnet", "payment_tx": "<mainnet sig>", "slot": {"next_available_at": "<iso>", "expires_if_unused_at": "<iso>"}}

The `PAYMENT-RESPONSE` header carries the mainnet settlement receipt.

## Beta limits

drip.0tx.io is in beta with 10 agent slots. An agent is the wallet that pays.

- Your first paid drip claims a slot. One slot per IP.
- Each slot gets one 0.1 SOL drip per rolling 24h.
- A slot frees up after 7 days with no drip.
- Each recipient address gets at most 0.1 SOL per rolling 24h.
- The whole faucet sends at most 1 SOL per UTC day.

## Errors

Refusals are never charged. Every check runs before settlement. Every error body has `error` (a code) and `message` (plain English).

| HTTP | error | Meaning |
|---|---|---|
| 400 | missing_devnet_address | No `devnet_address` in the body (note: the field is `devnet_address`, not `address`) |
| 400 | invalid_address | `devnet_address` is not a base58 Solana address |
| 400 | not_a_wallet | `devnet_address` is a token account or other PDA, not a wallet |
| 400 | invalid_amount | `sol` sent and not 0.1 |
| 402 | (x402 challenge) | Payment required or invalid. Body includes `slots: {total, taken}` |
| 403 | banned | Payer, IP or recipient banned. IPs that probe for secrets or exploits (e.g. `/.env`, `*.php`, path traversal) or scan many nonexistent paths are banned automatically for 30 days |
| 404 | not_found | No such endpoint. A wrong path is never penalized on its own; see this file for the real ones |
| 403 | ip_has_slot | Your IP already holds a slot under another wallet |
| 403 | payer_too_new | Paying wallet lacks on-chain history (only if the age check is enabled) |
| 429 | slot_cooldown | Your slot dripped in the last 24h. See `next_available_at` |
| 429 | recipient_limit | That address got 0.1 SOL in the last 24h. See `next_available_at` |
| 503 | beta_full | All 10 slots taken. See `slots`. Try later |
| 503 | sold_out_today | Daily cap reached. See `resets_at` (00:00 UTC) |
| 503 | out_of_stock | Faucet inventory low. Try later |
| 503 | payments_unavailable | Payment processing temporarily down. Try later |
| 429 | (no JSON body) | Rate limited: more than 60 requests/min from your IP to /v1/*. Wait a minute |
| 502 | delivery_pending | Paid but the devnet send failed. Retried automatically; keep `payment_tx` |

## Other endpoints

- GET /v1/stats: drips, SOL sent, unique payers, inventory, slots taken, today's output vs cap, runway.
- GET /v1/health: liveness and inventory.
- GET /openapi.json: machine-readable spec.
- GET /SKILL.md: these instructions as an agent skill.