Ethereum integration documentation

overview

402Dock connects paid HTTP resources to USDC and ETH settlement on Ethereum Mainnet. The order records the payment terms; the backend verifies the transaction before granting access.

The current integration uses the order API below. HTTP 402 responses include USDC payment requirements when a recipient is configured. Generic PAYMENT-SIGNATURE and PAYMENT-RESPONSE client handling is on the roadmap.

quickstart

Inspect the price, connect an Ethereum wallet, and approve the exact payment shown by checkout.

open checkout wallet guide

resource requests

# Read the resource's payment requirements
curl -i http://localhost:4020/api/demo/research

# Read payment configuration and available currencies
curl -s http://localhost:4020/api/config

# Complete checkout, then retrieve the resource with your paid order
curl -i http://localhost:4020/api/demo/research \
  -H "Authorization: Bearer <paid-order-id>"

network and assets

network: Ethereum Mainnet
chain ID: 1
network identifier: eip155:1
payments: USDC + native ETH
USDC contract: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
block explorer: Etherscan ↗

USDC amounts use 6 decimals. ETH amounts use 18 decimals. Each currency has its own displayed price; an ETH/USD conversion is not applied.

order and payment flow

Read the resource’s payment requirements and checkout status.
Create an order with the payer wallet and selected currency. The payment window is 15 minutes.
For USDC, sign the exact EIP-712 authorization returned with the order. The relayer submits the transfer using EIP-3009.
For ETH, submit the order’s transaction object from the payer wallet. Preserve its destination, value, chain ID, and order reference.
Verify the receipt and required confirmations using the order’s verify endpoint.
Request the resource with Authorization: Bearer <paid-order-id>. Access rechecks the payment receipt.

API reference

endpoint	purpose
`GET /api/config`	Network, currencies, resource prices, recipient, and checkout activation.
`GET /api/health`	RPC connection, settlement balance, USDC signing domain, and activation status.
`GET /api/demo/public`	A free resource response.
`GET /api/demo/research`	Payment requirements, or the resource for a verified paid order.
`POST /api/orders`	Create an order using the payer address and selected currency.
`GET /api/orders/:id`	Recover an order and its saved transaction hash.
`POST /api/orders/:id/authorize`	Submit an exact signed USDC authorization.
`POST /api/orders/:id/verify`	Verify the submitted transaction or recheck its saved receipt.

POST bodies use application/json. The API applies a shared limit of 120 requests per client IP per 60-second window.

create an order

curl -s http://localhost:4020/api/orders \
  -H "Content-Type: application/json" \
  -d '{"payer":"<your-Ethereum-address>","currency":"USDC"}'

USDC authorization

Sign the typedData returned with your order. Its domain is read from the USDC contract, and its message binds the payer, recipient, exact amount, expiry, and unique nonce.

submit authorization

POST /api/orders/<order-id>/authorize
Content-Type: application/json

{"signature":"<wallet-signature>"}

The server records the signed transaction before broadcasting. Retries use the identical transaction rather than creating another charge.

native ETH

Send the transaction returned with your order on Ethereum Mainnet. The unique reference in its data binds the transfer to the purchase. A plain transfer without the reference does not unlock the resource.

verify payment

POST /api/orders/<order-id>/verify
Content-Type: application/json

{"transactionHash":"<transaction-hash>"}

recovery and access

The browser saves the active order and transaction hash. Reopening checkout restores the purchase. If wallet submission is interrupted, recover the transaction hash from wallet activity and check the existing order before paying again.

Order IDs are bearer access credentials. Keep them private. The backend checks the successful receipt, canonical block, payment window, payer, recipient, amount, and confirmation policy before delivering access.

response status

400: Invalid request or authorization.
402: Payment required or not yet confirmed.
403: Origin or host does not match the deployment.
409: Conflicting payment or chain state.
410: Order expired before USDC authorization.
415: Missing application/json.
422: Failed transaction or mismatched payment.
429: Request limit exceeded.
503: Checkout not activated, settlement unavailable, or RPC operation failed.

deployment configuration

Serve the frontend and Node.js backend at your HTTPS origin. Supply a dedicated settlement signer, revenue recipient, and mainnet RPC. Persist the mainnet order database across deployments.

environment

PUBLIC_ORIGIN=https://<your-domain>
ETHEREUM_RPC_URL=<mainnet-rpc-url>
PAYMENT_RECIPIENT_ADDRESS=<revenue-wallet-address>
RELAYER_PRIVATE_KEY=<secret-from-your-secret-store>
CONFIRMATIONS=2
PAYMENTS_ENABLED=true

Activation requires the RPC, recipient, and settlement signer to be configured. Store signing credentials outside source control. The website and wallet flow already target mainnet; activation requires no frontend copy change.

deployment status