authorization

Halot uses x402 V2 for quote-bound payment authorization. This page covers the pre-funding step only: quote construction, the 402 challenge, and the signed authorization that allows the server to return a prepared job.

x402 Payment Lifecycle

The authorization flow lets agents negotiate pricing and finalize a payment intent before compute is executed or escrow is funded.

1. Payment Required (HTTP 402)

When a requester calls POST /jobs/prepare without a valid payment signature, the server returns a 402 response with a PAYMENT-REQUIRED header containing the encoded PaymentRequirement.

PaymentRequirementSchema = z.object({
  x402Version: z.literal(2),
  scheme: z.literal("exact"),
  quoteId: z.string(),
  accepts: z.array(QuoteAcceptOptionSchema).min(1),
  expiresAt: z.string(),
  resource: z.string(),
  description: z.string(),
  aggregatorUrl: z.string().optional(),
})

2. Payment Authorization

To continue, the requester signs the payment requirement and base64-encodes the resulting PaymentAuthorization into the PAYMENT-SIGNATURE header on the next POST /jobs/prepare call.

PaymentAuthorizationSchema = z.object({
  quoteId: z.string(),
  network: z.string(),       // 0g:testnet | 0g:mainnet | stellar:testnet | stellar:mainnet
  amount: z.string(),
  token: z.string(),
  payTo: z.string(),
  memo: z.string(),
  expiresAt: z.string(),
  requesterAddress: z.string(),
  signature: z.string(),
})

Quote Construction

QuotesService uses fixed protocol math: provider fee from the service, per-verifier fee, TeeML compute fee, and a percentage platform fee. The verifier count comes from the service trust level and is capped by the number of eligible verifiers currently available.

const verifierCount = resolveVerifierCount(trustLevel, baseFee);
// standard: 3 | thorough: 5 | critical: 7

const verifierFee = verifierCount * 0.50;
const computeFee = verifierCount * 0.25;
const platformFee = baseFee * 0.07;

const total = baseFee + verifierFee + computeFee + platformFee;

Once the signed authorization is accepted, Halot returns a prepared job and the flow moves into escrow funding.