Adding Tolls

Tolls define the x402 payment requirements for accessing a Gatepay link. You can specify which asset, network, and amount are required for access. This section explains how to configure tolls using the Gatepay SDK.

To delegate transaction fee payments using the x402 protocol, the user must have a positive credit balance in their Gatepay account. Gatepay will use this balance to cover transaction fees on the user’s behalf. Users can top up their account directly from the Gatepay dashboard.

What is a Toll?

A toll is a rule that enforces payment before granting access to a resource. Each toll specifies:

Network (e.g., Ethereum, Base, Polygon)
Asset (e.g., ETH, USDC)
Amount (exact amount required)
Destination address (where payment is sent)

Toll Configuration Example

The current SDK uses the following structure for payment requirements:

toll: {
    tollPaymentRequirements: [
        {
            assetNetwork: "base",
            amount: "1000000", // 1 USDC (6 decimals)
            assetAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC contract on Base
            destinationAddress: "0x742d35Cc6634C0532925a3b8D098C6dd9f67e235", // Your wallet
        },
    ]
}

Adding a Toll when Creating a Link

You can add tolls when creating a link using the createLink convenience method:

const link = await gatepay.createLink({
    name: "Premium Content",
    description: "Access to exclusive content",

    resource: {
        type: "link",
        data: {
            url: "https://example.com/premium-content",
        },
    },

    toll: {
        tollPaymentRequirements: [
            {
                assetNetwork: "base",
                amount: "1000000", // 1 USDC
                assetAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                destinationAddress: "your-wallet-address",
            },
        ],
    },
})

Adding a Toll to an Existing Link

You can also add tolls to existing links using the direct API:

// Add toll to existing link
await gatepay.links.postLinksByLinkUuidTolls({
    linkUuid: "your-link-uuid",
    postLinksByLinkUuidTollsRequest: {
        tollPaymentRequirements: [
            {
                assetNetwork: "base",
                amount: "1000000", // 1 USDC
                assetAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                destinationAddress: "your-wallet-address",
            },
        ],
    },
})

Multiple Payment Options

WORK IN PROGRESS Not Supported Yet

You can specify multiple payment requirements to give users different payment options:

toll: {
    tollPaymentRequirements: [
        {
            assetNetwork: "base",
            amount: "1000000",
            assetAddress: "0x....",
            destinationAddress: "your-wallet-address",
        },
        {
            assetNetwork: "ethereum",
            amount: "100000000000000000",
            assetAddress: "0x....",
            destinationAddress: "your-wallet-address",
        },
    ]
}

Supported assets

For a full list of supported assets, see Supported Networks.

Managing Tolls

Get Active Toll

const activeToll = await gatepay.links.getLinksByLinkUuidTollsActive({
    linkUuid: "your-link-uuid",
})

Delete Active Toll

await gatepay.links.deleteLinksByLinkUuidTollsActive({
    linkUuid: "your-link-uuid",
})

Tips & Best Practices

Use testnets for development and testing tolls.
Always verify the payTo address and asset contract.

See also: