Get started

Authentication

In Tael, the payment is the authentication — there are no API keys.

No keys, no accounts

Traditional APIs authenticate a caller with a shared secret (an API key or OAuth token) and bill them later. That assumes a human signed up first. Tael removes that step: an agent proves it is allowed to call your endpoint by paying for the call, in the same request. There is nothing to register and no credential to leak.

This is the x402 / HTTP-402 model: a resource answers 402 Payment Required with its price, the caller attaches a payment proof, and the server verifies it before doing any work.

The X-PAYMENT header

A paying client retries the request with an X-PAYMENT header: a base64-encoded JSON envelope containing a signed Stellar transaction (XDR) that transfers the required USDC to your payTo address.

{ }X-PAYMENT (decoded)

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "stellar-testnet",
  "payload": {
    "transaction": "<base64 signed Stellar XDR>"
  }
}

Tael validates the protocol invariants (scheme and network must match the challenge) and then hands the signed transaction to your PaymentVerifier, which settles it on Stellar. Only if settlement succeeds does your handler run.

The receipt

On success the response carries an X-PAYMENT-RESPONSE header — a base64 receipt proving settlement. Your handler also receives the settlement details as receipt so you can attribute the call to the paying wallet.

TShandler context

handler: async ({ request, receipt }) => {
  // receipt describes the settled payment (payer, amount, tx)
  return Response.json({ ok: true, paidBy: receipt.payer });
}

Networks

Tael settles in USDC on Stellar. Pick the network per environment:

stellar-testnet — for development, with the mock verifier or test USDC.
stellar-mainnet — for production, with the real Stellar verifier.

See the Node.js SDK reference for how to plug in the Stellar verifier.