feat(x402): apply the paid unlock to agent offers by type, not a configured path

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.

[bussyjd]

Makes the platform fee ship with the product instead of being an operator opt-in.

Problem

The paid unlock gate picked its offer by string-matching rule.StripPrefix against a global authCaptureUnlock.offerPrefix. Two consequences, both bad for a platform fee:

• an operator had to opt in by hand, and a node operator has no incentive to opt into a fee that goes to someone else;
• it covered exactly one offer per stack.

Change

isUnlockOffer now keys on the offer type:

returncfg!=nil&&cfg.AuthCaptureUnlock!=nil&&cfg.AuthCaptureUnlock.Enabled&&rule!=nil&&rule.AgentRuntime!=""

Every agent offer is unlock-gated; http offers never are. rule.AgentRuntime is already populated from the ServiceOffer (serviceoffer_source.go:306-308) and is the same signal mergeAgentExtras uses to decide a rule is an agent — no new plumbing.

Why type is the right axis

It matches how the two types are sold.

An agent is a conversation a human opens in the chat widget: connect wallet → pay once → session minted → per-turn billing, no further fee. An http offer is a machine-to-machine API with no session concept; gating it would tax per-request traffic that never signs in.

A stack typically hosts one or a few agent offers alongside many type: http APIs, so in practice a small number of offers become unlock-gated and the rest are untouched:

offer type	unlock + fee	why
agent	✅	human opens a session in the chat widget
http	—	machine-to-machine, no session to gate

Multi-agent correctness

Price, PayTo and Network become overrides, falling back to the agent offer's own values.

This is load-bearing the moment more than one agent is covered: without it every agent's unlock revenue would land in one wallet at one price. The fallbacks are applied beforeValidate() so it checks the values that will actually be advertised, and an unlock priced by neither config nor offer is now rejected rather than advertised at zero.

offerPrefix is removed.

Also

handleAuthEndpoints moves its existing authRuleForPrefix lookup above the check so it can test the rule rather than the path — same call, twelve lines earlier.

This also sidesteps the buyer-compatibility problem a fee-on-everything design would hit: auth-capture only ever appears on the agent unlock, which is a browser widget we control, so no third-party exact-only buyer encounters it.

Tests

unlock_agent_default_test.go pins the rule in both directions (agent gated, http not, a second agent also gated), keeps the operator kill switch honest, and covers the nil cases. Verified it fails when the selector is reverted to a prefix match:

--- FAIL: TestIsUnlockOffer_SelectsAgentsOnly
agent offer must be unlock-gated — the fee ships with the product, not per-offer opt-in
a second agent offer must also be unlock-gated (no one-offer-per-stack ceiling)

go build ./..., go vet, and the x402, serviceoffercontroller and embed suites all pass.

Sequencing — needs a follow-up on #818

#818 templates authCaptureUnlock into the Helm chart including offerPrefix, which this PR removes, and defaults enabled: false. If both land as-is the chart would render a dead key and the fee would stay off.

Whichever merges second should drop offerPrefix from base/values.yaml, the helmfile state values and the x402-pricing.md reference, and flip the default to enabled: true with the platform feeRecipient and bps — which is the whole point of type-based selection.

This PR deliberately does not touch those files, to keep the verifier change reviewable on its own.

[bussyjd]

Closing: the mechanism this PR broadens does not reach the traffic it was aimed at.

isUnlockOffer is only consulted inside if rule.IsAuth() (internal/x402/verifier.go), so the unlock only ever applies to gate: auth routes. Auth routes take a verified wallet instead of payment (internal/x402/config.go), which means the turns behind a minted session are free — so a fee attached there fires exactly once per session and can never be per-turn.

Agent offers that declare no routes get {Path: "/*", Gate: paid} from EffectiveRoutes(), so in practice they never enter the auth branch at all and this PR would gate nothing.

Separately, the chat widget bundles ExactEvmScheme only, so an auth-capture challenge would be unpayable by the shipped client — the buyer-compatibility argument in the commit message does not hold.

The per-turn payments are ordinary paid requests built by BuildV2RequirementWithAsset (hardcoded Scheme: "exact", no fee fields). That is where a recurring platform fee has to go. Superseding PR to follow.

[bussyjd]

Superseded by #820, which puts the fee on the per-request paid path instead.