Blink Labs x402
Pay-per-use access to Cardano node APIs. You buy a time-limited, metered session with a single payment in a stablecoin or ADA, and use it right away. There is no account and no API key: your wallet is your identity, and the payment is the purchase.
This service uses the x402 protocol, so any x402 client can buy a session. An agent-readable version of this page is at /llms.txt and the catalog as JSON is at /catalog.json.
Quickstart
- Choose a product: a service, the Cardano network whose data you want, and a session length (see Services and Prices).
- Buy it: request
https://pay.x402.blinklabs.cloud/v1/sessions?service=name&network=network&duration=length. The answer is402 Payment Requiredlisting the ways to pay. An x402 client signs a payment for one of them and sends the same request again with it in thePAYMENT-SIGNATUREheader. The200answer is your session, for example:{ "session_id": "…", "token": "…", "expires_at": "…", "endpoint": "https://x402.blinklabs.cloud", "allowance": 22000 } - Use it: send requests to
endpointwithAuthorization: Bearer tokenuntil the session expires or its allowance is used up.
Example: paying with USDC on an EVM chain
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.WALLET_KEY)));
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://pay.x402.blinklabs.cloud/v1/sessions?service=kupo&network=mainnet&duration=1h");
const session = await res.json();
const data = await fetch(session.endpoint + "/health", {
headers: { Authorization: "Bearer " + session.token },
});
A payment is a signature, not a transaction you send: the facilitator submits it, so the wallet needs the token but not gas.
Example: paying on Cardano
A Cardano payment is a signed transaction, and it takes about a minute to confirm, so the broker may answer 503 while it is in flight. The rule is to send the same signed payment again, never sign a new one. A client that signs again pays twice, and the second payment is refused with 409 while the first is pending. wrapFetchWithPayment does not resend, so keep the signed header and resend it yourself:
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { toClientCardanoSigner } from "@x402/cardano";
import { ExactCardanoScheme } from "@x402/cardano/exact/client";
const signer = toClientCardanoSigner({
mnemonic: process.env.WALLET_MNEMONIC,
network: "cardano:mainnet",
provider: { koios: { baseUrl: "https://api.koios.rest/api/v1" } },
});
const client = new x402Client();
// The Cardano client signs only assets it is told about, and caps a payment at $1 unless you raise it.
client.setSpendControls({
allowedAssets: [{ network: "cardano:mainnet", asset: "lovelace", maxAmountPerPayment: "20000000" }],
});
client.register("cardano:*", new ExactCardanoScheme(signer));
let signed;
const keepPayment = (input, init) => {
const h = input instanceof Request ? input.headers : new Headers(init?.headers);
if (h.get("payment-signature")) signed = h.get("payment-signature");
return fetch(input, init);
};
const pay = wrapFetchWithPayment(keepPayment, client);
const url = "https://pay.x402.blinklabs.cloud/v1/sessions?service=kupo&network=mainnet&duration=24h";
let res = await pay(url);
while (res.status === 503) {
await new Promise((r) => setTimeout(r, 5000));
res = await fetch(url, { headers: { "payment-signature": signed } });
}
const session = await res.json();
A token payment also sends the ADA its output must carry (about 1.2 ADA) to the recipient, besides the network fee. If you walk away after a 503 you have still paid: the broker finishes the sale, and sending the same signed payment later returns your session.
Services
Every service is sold for each network listed. A session is bound to the service and network you bought, and the API you call is that service's own API.
| Service | What it is | Networks | Connections | Requests/s |
|---|---|---|---|---|
blockfrost | Blockfrost-compatible REST API, including transaction submission (POST /tx/submit). | mainnet, preprod, preview | 10 | 20 |
kupo | Kupo chain indexer REST API. | mainnet, preprod, preview | 10 | 20 |
ogmios | Ogmios WebSocket API. | mainnet, preprod, preview | 2 | 50 |
ogmios-v7 | Ogmios v7 WebSocket API. | mainnet, preprod, preview | 2 | 50 |
utxorpc | UTxO RPC over gRPC. | mainnet, preprod, preview | 2 | 20 |
Connections is the most requests, streams or connections one session may have open at once. Requests/s is the most one session may send each second.
Prices
A session sells an allowance of metered units for a window of time, whichever ends first. A unit is one HTTP request (including a WebSocket handshake), one gRPC call (a stream counts as one call), or one message the backend sends on a WebSocket. Messages you send on a WebSocket are rate limited, not metered. Prices are in US dollars and are paid in the options below.
blockfrost, kupo, ogmios, ogmios-v7, utxorpc
| Session | Price | Allowance | USDC on Base | USDC on Arc | ADA on Cardano | USDCx on Cardano | USDM on Cardano |
|---|---|---|---|---|---|---|---|
| 5m | $0.01 | 2200 | 0.01 | 0.01 | not offered | not offered | not offered |
| 1h | $0.10 | 22000 | 0.1 | 0.1 | not offered | not offered | not offered |
| 24h | $2.00 | 440000 | 2 | 2 | 8 | 2 | 2 |
Cardano payments are offered for sessions of $1.00 and up, because a Cardano output must carry a minimum amount of ADA. ADA is priced at a rate Blink Labs sets and may change; the 402 always states the exact amount.
How to pay
These are the payment options and the address each one pays. Before you sign, check that the payment you are asked to make goes to the address listed here.
| Chain | Asset | Pays to |
|---|---|---|
| Base | USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 0xd22C46b55deE9723394F287e2014A25c0562730D |
| Arc | USDC 0x3600000000000000000000000000000000000000 | 0xd22C46b55deE9723394F287e2014A25c0562730D |
| Cardano | ADA lovelace | addr1q8g9808jhwhqjp3ylqgdpzzuur4u53n5zv4ahadskq6djd3lwzwsdphplcdpzla0vnksx0vd2xk70ykyfl3fmuwxr4vqv7tkrw |
| Cardano | USDCx 1f3aec8bfe7ea4fe14c5f121e2a92e301afe414147860d557cac7e34.5553444378 | addr1q8g9808jhwhqjp3ylqgdpzzuur4u53n5zv4ahadskq6djd3lwzwsdphplcdpzla0vnksx0vd2xk70ykyfl3fmuwxr4vqv7tkrw |
| Cardano | USDM c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad.0014df105553444d | addr1q8g9808jhwhqjp3ylqgdpzzuur4u53n5zv4ahadskq6djd3lwzwsdphplcdpzla0vnksx0vd2xk70ykyfl3fmuwxr4vqv7tkrw |
Who processes the payment. USDC payments on chains configured for Circle are verified and settled by Circle's x402 Facilitator Service: it checks your signature, screens the addresses on both sides, and submits the transfer on chain (Circle pays the gas). Circle's Developer Terms, Service Terms and Privacy Policy apply to what Circle does, and its documentation describes the service. A payment Circle declines to settle does not buy a session. Cardano payments are verified and submitted by Blink Labs' own facilitator, with no third party in between.
USDC payments on chains configured for Coinbase CDP are verified and settled by the Coinbase CDP Facilitator. Coinbase screens the payment and submits the transfer on chain. A payment Coinbase declines to settle does not buy a session.
- Payments are final. A session is sold as described here and there are no automatic refunds. If a payment was taken and no session reached you, or you were charged twice, write to support@blinklabs.io (see Support).
- Sending the same signed payment again returns the same session and is never charged twice.
- Use a dedicated wallet for payments and put spend limits on your client: it signs whatever the
402asks for, up to the limits you set.
Using a session
- Authentication. Send the token as
Authorization: Bearer tokenon every request. It is accepted nowhere else: not in a query string, not in a cookie. For gRPC, send it asauthorizationmetadata. - Paths. After the token, the path and query are the service's own API, passed through unchanged.
- WebSockets. Open the connection with the
Authorizationheader. Browsers cannot set it on a WebSocket, so use a server-side client. - Balance. HTTP responses carry
X-X402-Allowance-Remaining. WebSocket and gRPC sessions have no such header, so keep your own count. - Connections. A restart on our side drops WebSocket connections. Reconnect with the same token while the session is valid.
- Several sessions. You may hold more than one at once. Every session costs the same per unit.
When a session ends
| Cause | HTTP | gRPC | WebSocket |
|---|---|---|---|
| Time ran out | 401 session expired | HTTP 401 | closed with code 4401 |
| Allowance used up | 429 session allowance exhausted, no Retry-After | RESOURCE_EXHAUSTED | closed with code 4429 |
| Too fast, or too many open at once | The call or handshake is refused with HTTP 429 and a Retry-After header. | ||
| Service busy | The call or handshake is refused with HTTP 503 and a Retry-After header. | ||
A refused request spends nothing. When a session ends, buy a new one.
Errors when buying
| Status | Meaning | What to do |
|---|---|---|
402 | Payment required, or the payment you sent was not accepted; the body says why. | Sign a payment for one of the listed options and send it. |
409 | The payment is already in use or in progress, or a payment from the same wallet for the same product is still settling. | Resend the first signed payment, or wait for it to settle. Do not sign a new one. |
429 | Too many payments from your address. | Wait and retry; Retry-After says how long. |
503 | Your payment is in flight (the body says settlement unresolved, retry), or the service is busy or unavailable. | Send the same signed payment again after Retry-After. |
An error body is JSON with an error field, and sometimes a reference (a session id). Quote it if you write to support.
Support
Write to support@blinklabs.io for anything that went wrong with a payment or a session. Please include:
- the
session_idorreferencefrom the response, if you have one; - the transaction hash of the payment, if you have one;
- the service, network and session length you were buying, and roughly when.
Never send a private key or a wallet mnemonic.