x402 wire format

tap.x402 carries the codecs for the three x402 headers TAP uses.

Headers

Header	Direction	Module
X-PAYMENT-REQUIREMENTS	Producer → Consumer (in 402)	tap.x402.requirements
X-PAYMENT	Consumer → Producer (open channel)	tap.x402.payment
X-PAYMENT-RESPONSE	Producer → Consumer (open ack)	tap.x402.response
X-TAP-COMMIT	Consumer → Producer (every K tokens)	tap.protocol.codec

All four are base64(json(payload)). See Wire format for byte layouts.

PaymentRequirements

The producer-published session terms. Consumed by the consumer's discovery + policy audit.

from tap.x402.requirements import PaymentRequirements, encode_requirements, decode_requirements, SCHEME

req = PaymentRequirements(
    scheme=SCHEME,
    network="solana-devnet",
    asset="<USDC mint>",
    recipient="<channel program id>",
    producer_pubkey="<base58>",
    input_price_micro=1,
    output_price_micro=5,
    max_unpaid_micro=5_000,
    trailing_buffer_tokens=10,
    duration_secs=300,
    dispute_secs=30,
    grace_ms=200,
    pause_timeout_ms=30_000,
    channel_open_url="https://provider/v1/messages",
    stream_url="https://provider/v1/messages",
    tokenizer_id="tap.tok.v1",
    input_token_count=42,        # set on prompt-bound 402; 0 on generic
    prepaid_input_micro=42,      # = input_token_count × input_price_micro
    model="gemini-2.5-flash",
)

header = encode_requirements(req)            # base64 string for HTTP header
roundtrip = decode_requirements(header)      # back to PaymentRequirements
assert roundtrip == req

OpenChannelPayment

The consumer's signed X-PAYMENT payload. Carries the channel-open parameters and the base64-encoded Solana transaction.

from tap.x402.payment import OpenChannelPayment, encode_payment

payment = OpenChannelPayment(
    scheme=SCHEME,
    network="solana-devnet",
    consumer_pubkey="<base58>",
    session_key="<base58>",
    nonce=12345,
    deposit_micro=50_000,
    input_price_micro=1,
    output_price_micro=5,
    prepaid_input_micro=42,
    duration_secs=300,
    dispute_secs=30,
    trailing_buffer_tokens=10,
    transaction_b64=base64.b64encode(bytes(signed_tx)).decode(),
)

header = encode_payment(payment)

PaymentResponse

The producer's X-PAYMENT-RESPONSE ack with the channel ID.

from tap.x402.response import PaymentResponse, encode_response

resp = PaymentResponse(
    tx_hash="<base58>",
    settlement="confirmed",
    channel_id="<base58 PDA>",
    channel_state="active",
)

Schema versioning

The scheme field is tap.v1.channel and the commit schema field is tap.v1.commit. Bumping either is a breaking change; consumers and producers must agree on the same schema string at session open. The reference SDK validates scheme strictly and raises X402Error on mismatch.