x402-contracts

Smart contracts for the x402 payment protocol on TRON and EVM chains. Enables gasless, signature-based (EIP-712) payment authorizations and native token settlement.

---

What is x402?

x402 is an open, neutral standard for internet-native payments. It brings to life the HTTP 402 Payment Required status code so that servers can request payment from clients in a programmatic way—ideal for API paywalls, agent-to-agent payments, and micropayments.

• Zero protocol fees — only network fees
• HTTP-native — payment flows fit into normal HTTP requests
• Multi-chain — this repo provides the TRON and EVM implementation

---

Features

• EIP-712 typed permits — Users sign payment details off-chain; a relayer or backend calls permitTransferFrom with the signature.
• Gasless for the signer — The submitter pays gas; the signer only needs a one-time approve of the Permit402 contract.
• Optional fee — Permit can include feeTo and feeAmount for protocol or facilitator fees.
• Replay protection — Nonce bitmap per owner; time window via validAfter / validBefore.

---

Architecture

Component	Role	File(s)
Permit402 (EVM)	Entry point for EVM chains (Ethereum, BSC, etc.)	contracts/evm/Permit402.sol
Permit402 (TRON)	Entry point for TRON (USDT-compatible)	contracts/tron/Permit402.sol
Permit402Base	Shared logic, EIP-712, nonce	contracts/core/Permit402Base.sol
PermitHash	EIP-712 struct hashes	contracts/libraries/PermitHash.sol
EIP712	Domain separator and typed data hashing	contracts/core/EIP712.sol
IPermit402	Structs and interface for permits	contracts/interface/IPermit402.sol

Flow: User signs Permit402Details (payment, fee, validity, nonce) → Relayer/backend calls permitTransferFrom(permit, owner, signature) → Contract pulls tokens from owner to payTo (and optional feeTo) in one shot.

---

Deployed Addresses

Network	Chain / Environment	Permit402 Address
TRON Mainnet	Mainnet	TT8rEWbCoNX7vpEUauxb7rWJsTgs8vDLAn
TRON Nile	Testnet	TFxDcGvS7zfQrS1YzcCMp673ta2NHHzsiH
TRON Shasta	Testnet	TR2XninQ3jsvRRLGTifFyUHTBysffooUjt

Network	Chain / Environment	Permit402 Address
BSC Mainnet	Mainnet	0x105a6f4613a1d1c17ef35d4d5f053fa2e659a958
BSC Testnet	Testnet	—

---

Deploy

• EVM (ethereum, sepolia, bsc, bscTestnet): npx hardhat deploy --network <network>
• TRON (tron, nile, shasta): npx hardhat deploy --network <network>

---

Build & Test

# Compile (Hardhat, with tronSolc for TRON targets)
npx hardhat compile

# Test with Foundry
forge test -vvv

# Test with Hardhat
npx hardhat test

---

Project Layout

├── contracts/
│   ├── core/
│   │   ├── Permit402Base.sol     # Shared permit logic (abstract)
│   │   └── EIP712.sol            # EIP-712 domain and hashing
│   ├── evm/
│   │   └── Permit402.sol         # EVM implementation (Ethereum, BSC, etc.)
│   ├── tron/
│   │   └── Permit402.sol         # TRON implementation (USDT-compatible)
│   ├── interface/
│   │   ├── IPermit402.sol        # Permit structs and interface
│   │   ├── IEIP712.sol
│   │   └── IERC1271.sol
│   └── libraries/
│       ├── PermitHash.sol        # TypeHashes and struct hashes
│       └── SafeTransferLib.sol   # EVM safe transfer (returns bool)
├── deploy/                       # EVM deploy scripts (hardhat-deploy)
├── deployTron/                   # TRON deploy scripts (sunhat)
├── test/
├── hardhat.config.ts             # Hardhat + sunhat + hardhat-foundry config
├── foundry.toml                  # Foundry config (tests & remappings)
└── AGENTS.md                     # Guidelines for AI/agent use of this repo

---

Integration

1. Domain & types — Use the same EIP-712 domain name "Permit402" and the struct definitions from IPermit402.sol and PermitHash.sol so that hashes match the contract. Domain separator uses block.chainid and contract address (see contracts/core/EIP712.sol).
2. ChainId for signing — When building EIP-712 typed data, use the chainId of the target network so the signature matches the contract. Wallet/TronLink must use the same chainId.
3. Sign off-chain — Build Permit402Details (meta, buyer, caller, payment, fee, delivery), hash with PermitHash and domain separator, then sign (e.g. 65-byte r || s || v).
4. Submit on-chain — Call permitTransferFrom(permit, transferDetails, owner, signature). The owner must have approved the Permit402 contract for the payToken (and have sufficient balance for amount plus optional feeAmount).

For full struct and field definitions, see contracts/interface/IPermit402.sol.

---

Security

• Access: Only the signer's signature authorizes transfers; no single admin can move user funds.
• Replay: Nonces and validAfter/validBefore limit replay across chains and time.

We welcome responsible disclosure. Please report issues privately before public disclosure when possible.

---

License

MIT. See LICENSE for full text.

---

Contributing

1. Fork the repo and open a branch from main.
2. Follow existing style (Solidity ^0.8.20, existing patterns in Permit402Base.sol and PermitHash.sol).
3. Add or update tests for new behavior.
4. Open a PR with a clear description; maintainers will review.

For agent/AI usage of this codebase, see AGENTS.md.