Skip to content

Commit ba19416

Browse files
brendanjryanbrendanjryan
authored
docs: add hosted fee payer page (#460)
1 parent 7867c9e commit ba19416

5 files changed

Lines changed: 172 additions & 3 deletions

File tree

‎src/pages/accounts/server/handler.feePayer.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ description: Deprecated — use Handler.relay with feePayer option instead.
99
`Handler.feePayer` has been deprecated. Use [`Handler.relay`](/accounts/server/handler.relay) with the [`feePayer`](/accounts/server/handler.relay#feepayer) option instead.
1010
:::
1111

12+
:::tip
13+
Looking for Tempo-hosted sponsorship endpoints? See [Hosted Fee Payer](/developer-tools/fee-payer). Use [`Handler.relay`](/accounts/server/handler.relay) when you need to run your own fee payer service.
14+
:::
15+
1216
## Migration
1317

1418
Replace `Handler.feePayer` calls with `Handler.relay` and nest the `account` under `feePayer`:

‎src/pages/developer-tools/fee-payer.mdx‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Hosted Fee Payer
3+
description: Sponsor Tempo transaction fees with Tempo's hosted fee payer endpoints for testnet development and approved mainnet integrations.
4+
---
5+
6+
import { Cards, Card } from 'vocs'
7+
8+
# Hosted Fee Payer
9+
10+
Tempo Labs provides hosted fee payer endpoints for applications that want to sponsor Tempo transaction fees without running fee payer infrastructure.
11+
12+
## Hosted endpoints
13+
14+
The hosted endpoints are JSON-RPC relays backed by [`Handler.relay`](/accounts/server/handler.relay). They are CORS-enabled and return standard JSON-RPC responses.
15+
16+
| Network | URL | Chain ID | Access |
17+
| --- | --- | --- | --- |
18+
| Mainnet | `https://sponsor.tempo.xyz/tp_<api_key>` | `4217` | Approved integrations with an API key |
19+
| Testnet | `https://sponsor.moderato.tempo.xyz` | `42431` | Public development and testing |
20+
21+
### Rate limits and policy
22+
23+
Hosted fee payer endpoints are rate-limited and may reject requests that fall outside the configured sponsorship policy.
24+
25+
Clients should avoid retry loops, back off after errors, and treat sponsorship as conditional. If sponsorship is rejected, the client should either let the user pay their own fee or retry through an application-owned fee payer.
26+
27+
### Pricing and access
28+
29+
The public testnet fee payer is free for development and testing.
30+
31+
Mainnet hosted fee payer access is intended for approved integrations and partner programs. Use `https://sponsor.tempo.xyz/tp_<api_key>` after your integration has been approved and you have been provided an API key. For production use outside the hosted policy, contact Tempo or run your own fee payer with [`Handler.relay`](/accounts/server/handler.relay).
32+
33+
## Using in production
34+
35+
Run your own fee payer when you need:
36+
37+
- Custom allowlists, rate limits, or per-user sponsorship rules
38+
- Dedicated funding, accounting, or reconciliation
39+
- Full control over availability, latency, and operational policy
40+
- Sponsorship for traffic that is not covered by Tempo's hosted policy
41+
42+
See [Sponsor User Fees](/guide/payments/sponsor-user-fees) to deploy your own fee payer service.
43+
44+
## Configure clients
45+
46+
### Tempo Wallet
47+
48+
```ts twoslash [wagmi.config.ts]
49+
import { tempoModerato } from 'viem/chains'
50+
import { createConfig, http } from 'wagmi'
51+
import { tempoWallet } from 'wagmi/connectors'
52+
53+
export const config = createConfig({
54+
connectors: [
55+
tempoWallet({
56+
feePayer: 'https://sponsor.moderato.tempo.xyz',
57+
}),
58+
],
59+
chains: [tempoModerato],
60+
transports: {
61+
[tempoModerato.id]: http(),
62+
},
63+
})
64+
```
65+
66+
### WebAuthn or custom transports
67+
68+
Use [`withRelay`](https://viem.sh/tempo/transports/withRelay) to route transaction fill and sponsorship requests through the hosted fee payer.
69+
70+
```ts twoslash [wagmi.config.ts]
71+
import { tempoModerato } from 'viem/chains'
72+
import { withRelay } from 'viem/tempo'
73+
import { createConfig, http } from 'wagmi'
74+
import { webAuthn } from 'wagmi/tempo'
75+
76+
export const config = createConfig({
77+
connectors: [webAuthn({ authUrl: '/auth' })],
78+
chains: [tempoModerato],
79+
transports: {
80+
[tempoModerato.id]: withRelay(
81+
http(),
82+
http('https://sponsor.moderato.tempo.xyz'),
83+
),
84+
},
85+
})
86+
```
87+
88+
For mainnet, replace the testnet URL with `https://sponsor.tempo.xyz/tp_<api_key>` after your integration has been approved and you have been provided an API key.
89+
90+
## Query the fee payer
91+
92+
### Chain ID
93+
94+
```bash
95+
curl -X POST "https://sponsor.moderato.tempo.xyz" \
96+
-H "Content-Type: application/json" \
97+
-d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
98+
```
99+
100+
### Fill a sponsored transaction
101+
102+
`eth_fillTransaction` returns a filled Tempo transaction plus metadata describing whether the request is sponsored.
103+
104+
```bash
105+
curl -X POST "https://sponsor.moderato.tempo.xyz" \
106+
-H "Content-Type: application/json" \
107+
-d '{
108+
"jsonrpc": "2.0",
109+
"id": 1,
110+
"method": "eth_fillTransaction",
111+
"params": [{
112+
"from": "0x0000000000000000000000000000000000000001",
113+
"calls": [{
114+
"to": "0x20c0000000000000000000000000000000000000",
115+
"data": "0x70a08231000000000000000000000000000000000000000000000000000000000000dead"
116+
}]
117+
}]
118+
}'
119+
```
120+
121+
A sponsored response includes `capabilities.sponsored: true` and sponsor metadata.
122+
123+
## API reference
124+
125+
| Method | Description |
126+
| --- | --- |
127+
| `eth_chainId` | Returns the chain ID served by the endpoint |
128+
| `eth_fillTransaction` | Fills transaction fields and returns sponsorship metadata |
129+
| `eth_signRawTransaction` | Adds the fee payer signature and returns the dual-signed raw transaction |
130+
| `eth_sendRawTransaction` | Adds the fee payer signature and broadcasts the transaction |
131+
| `eth_sendRawTransactionSync` | Adds the fee payer signature, broadcasts the transaction, and waits for a receipt |
132+
133+
:::info
134+
Fee sponsorship requires a Tempo Transaction. The sender signs with sponsorship enabled, then the fee payer counter-signs with `feePayerSignature`.
135+
:::
136+
137+
## How it works
138+
139+
Tempo Transactions support native fee sponsorship through a separate fee payer signature. The user signs the transaction first, leaving fee token selection to the fee payer. The hosted fee payer validates the request, chooses the fee token, signs the fee payer payload, and either returns the completed transaction or broadcasts it depending on the JSON-RPC method.
140+
141+
No paymaster contract, bundler, or EntryPoint contract is required.
142+
143+
## Next steps
144+
145+
<Cards>
146+
<Card icon="lucide:wallet" title="Sponsor User Fees" description="Build gasless payment flows and deploy your own fee payer service." to="/guide/payments/sponsor-user-fees" />
147+
148+
<Card icon="lucide:server" title="Handler.relay" description="Run a custom relay with fee payer sponsorship and validation policy." to="/accounts/server/handler.relay" />
149+
150+
<Card icon="lucide:file-code" title="Tempo Transaction Spec" description="Read the fee payer signature details in the transaction spec." to="/protocol/transactions/spec-tempo-transaction#fee-payer-signature-details" />
151+
</Cards>

‎src/pages/guide/payments/sponsor-user-fees.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ import PublicTestnetSponsorTip from '../../../snippets/public-testnet-sponsor-ti
1414

1515
Enable gasless transactions by sponsoring transaction fees for your users. Tempo's native fee sponsorship allows applications to pay fees on behalf of users, improving UX and removing friction from payment flows.
1616

17+
:::tip[Hosted fee payer]
18+
Use Tempo's [hosted fee payer endpoints](/developer-tools/fee-payer) for testnet development or approved mainnet integrations. Run your own fee payer when you need custom sponsorship policy, accounting, or operational control.
19+
:::
20+
1721
## Demo
1822

1923
<Demo.Container name="Sponsor User Fees" footerVariant="source" src="tempoxyz/accounts/tree/main/examples/with-fee-payer">
@@ -29,7 +33,7 @@ Enable gasless transactions by sponsoring transaction fees for your users. Tempo
2933
### Set up the fee payer service
3034

3135
:::tip
32-
Tempo provides a public testnet fee payer service at `https://sponsor.moderato.tempo.xyz` that you can use for development and testing. If you want to run your own, follow the instructions below.
36+
Tempo provides a public testnet fee payer service at `https://sponsor.moderato.tempo.xyz` that you can use for development and testing. See [Hosted Fee Payer](/developer-tools/fee-payer) for endpoint details, or follow the instructions below to run your own.
3337
:::
3438

3539
You can stand up a minimal fee payer service using the [`Handler.relay`](/accounts/server/handler.relay) handler provided by the [Tempo Accounts SDK](/accounts). To sponsor transactions, you need a funded account that will act as the fee payer.

‎src/snippets/public-testnet-sponsor-tip.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
:::tip
2-
Tempo provides a public testnet fee payer service at `https://sponsor.moderato.tempo.xyz` that you can use for development and testing. If you want to run your own, follow the instructions below.
3-
:::
2+
Tempo provides a public testnet fee payer service at `https://sponsor.moderato.tempo.xyz` that you can use for development and testing. See [Hosted Fee Payer](/developer-tools/fee-payer) for endpoint details, or follow the instructions below to run your own.
3+
:::

‎vocs.config.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -756,6 +756,16 @@ export default defineConfig({
756756
{
757757
text: 'Tempo Developer Tools',
758758
items: [
759+
{
760+
text: 'Hosted Services',
761+
collapsed: true,
762+
items: [
763+
{
764+
text: 'Hosted Fee Payer',
765+
link: '/developer-tools/fee-payer',
766+
},
767+
],
768+
},
759769
{
760770
text: 'Accounts SDK',
761771
link: '/accounts',

0 commit comments

Comments
 (0)