Developer Sandbox

Complete developer documentation for the 402bin protocol, API endpoints, payment flow, and client-side cryptographic contracts.

Warning block

Paying to unlock a bin without its decryption key buys undecryptable ciphertext. The API cannot check key possession. No refunds.

Endpoints

The 402bin service provides standard API endpoints for creating, retrieving, and verifying paywalled pastes. An OpenAPI specification is available at /api/openapi.json.

POST/api/bins

Create a new paywalled encrypted bin. This requires payment of the platform creation fee, quoted dynamically in the 402 header.

Request Body (JSON)

{
  "id": "2d7y4aP2W...",
  "content_blob": "{\"ciphertext\":\"...\",\"iv\":\"...\"}",
  "mime_type": "text/plain",
  "price_atomic": 500000,
  "creator_wallet": "0x6f3...B02",
  "expires_in_ms": 86400000
}

Response (200 OK)

{
  "url": "https://402bin.com/v/2d7y4aP2W..."
}

GET/api/bins/:id

Retrieve the contents of a bin. If the bin is locked, a 402 response is returned with the bin's public metadata. If unlocked (with valid signature), a 200 response returns the content blob.

Unpaid Response (402 Payment Required)

{
  "id": "2d7y4aP2W...",
  "price_atomic": 500000,
  "creator_wallet": "0x6f3...B02",
  "evm_split_address": "0x3da...6a1",
  "platform_allocation_ppm": 200000,
  "mime_type": "text/plain"
}

Paid Response (200 OK)

{
  "content_blob": "{\"ciphertext\":\"...\",\"iv\":\"...\"}",
  "mime_type": "text/plain"
}

GET/api/openapi.json

Returns the complete OpenAPI 3.1.0 document detailing all paths, parameters, schemas, and payment flow requirements.

Payments

All transactions on 402bin.com are paid using USDC via the x402 protocol v2. When an API request requires payment, the server responds with a 402 Payment Required status code containing a base64-encoded payment configuration inside the PAYMENT-REQUIRED header.

Protocol Details

Protocol Version	x402 V2
EVM Network	eip155:84532 (Base Sepolia)
USDC Asset Address	0x036CbD53842c5426634e7929541eC2318f3dCF7e
x402 Facilitator	https://x402.org/facilitator

Clients process the payment details, construct a signed EIP-3009 transfer authorization, obtain a settlement signature from the facilitator, and submit the signature back in the PAYMENT-SIGNATURE header.

Example using @x402/fetch & ExactEvmScheme

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// Create an EVM account signer
const account = privateKeyToAccount("0xYourPrivateKey");

// Wrap native fetch with x402 payment handling for Base Sepolia
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [
    {
      network: "eip155:84532", // Base Sepolia
      client: new ExactEvmScheme(account),
    },
  ],
});

// Request that handles payments automatically
const response = await fetchWithPayment("https://402bin.com/api/bins/some-bin-id", {
  method: "GET",
});

const data = await response.json();

Client-side crypto contract

All pastes created on 402bin are encrypted end-to-end on the client before being sent. 402bin developers and agents can write independent clients by conforming to the following cryptographic specification:

Encryption Algorithm: AES-256-GCM is used for payload encryption.

Key Derivation: Clients generate a secure, random 32-byte key.

Initialization Vector (IV): A fresh, cryptographically secure 12-byte IV must be generated for each encryption operation.

Content Wire Format: The payload stored in the database's content_blob is a JSON-encoded string with base64-encoded fields:

content_blob = JSON.stringify({ ciphertext: "base64", iv: "base64" })

Deterministic Bin ID: The id of the bin is derived by running SHA-256 over the raw 32-byte key, followed by base58btc encoding:

bin id = base58btc(SHA-256(raw key))

Share URL format: https://402bin.com/v/<id>#key=<base58btc(raw key)>
Because the key is only transmitted in the URL fragment (after the #), it is never sent to the server in HTTP requests, maintaining a strict zero-knowledge model.

Payouts

Unlock payments do not go to a central platform wallet. Instead, payments for each paste are routed to a deterministic split contract deployed using 0xSplits V2 on Base Sepolia.

Deterministic 0xSplits V2 Parameters

The Split address is derived deterministically using the following configuration parameters:

Split Type	Push split
Factory Address	0xaDC87646f736d6A82e9a6539cddC488b2aA07f38
Split Owner	0x0000000000000000000000000000000000000000 (Immutable)
Salt	0x0000000000000000000000000000000000000000000000000000000000000000
Distributor Fee	0%
Allocations	Platform Treasury receives a calculated share (details on 402 metadata, e.g. 200,000 ppm = 20%). The Paste Creator receives the remainder.

To collect: Anyone can trigger deployment of the split by calling createSplit with these exact params, and distribute accumulated USDC using distribute on the factory contract.