This guide uses Viem for smart contract interactions, which is the recommended Ethereum library for modern applications. Viem provides better TypeScript support, improved performance, and a more intuitive API compared to ethers.js.
Starknet, Tron and Solana: this page documents EVM contract calls only. For those networks, use the Sender API Integration with
network: "starknet", "tron" or "solana". Tron and Solana orders are created through the v2 Sender API only. Token contracts for these networks are listed under Supported Stablecoins.Overview
The Gateway contract is a multi-chain EVM-based smart contract that facilitates the on-chain lifecycle of payment orders. It empowers users to create off-ramp orders while enabling liquidity providers to facilitate those orders at competitive exchange rates.Prerequisites
- Paycrest Sender Account: Register at app.paycrest.io and complete KYB verification. You’ll need your API Key to embed in every order’s encrypted metadata: this links the on-chain order to your sender profile and enables webhooks.
- Ethereum Provider: MetaMask, WalletConnect, or any Web3 provider
- Viem: For smart contract interactions
- USDT/USDC Balance: Sufficient token balance for orders
- Gas Fees: ETH for transaction fees
Connect Wallet
- JavaScript
- Python
- Go
- cURL
Initialize Contracts
- JavaScript
- Python
- Go
- cURL
Create an Order
- JavaScript
- Python
- Go
- cURL
Exchange Rate and Account Verification
For mobile money recipients, you may pass local MSISDN (e.g. KES
07…); POST /v2/verify-account normalizes dial codes server-side. Optional metadata on verify applies for KES Till/Paybill. See Verify Account.data.sell.providerIds—the ranked provider queue for the corridor. Read it alongside rate if you want to carry that queue into the encrypted recipient as providerIds (see Routing fields).
- JavaScript
- Python
- Go
- cURL
Data Encryption
The recipient object is encrypted with the aggregator’s public key to produce themessageHash passed to the contract. Always include your API Key in the metadata.apiKey field: this is the same key used as the API-Key header in REST requests, and it links the on-chain order to your sender profile, enabling webhooks and order attribution.
Your API Key is available in the dashboard at app.paycrest.io.
On EVM networks you can additionally tag orders with a public on-chain ERC-8021 data suffix. The suffix does not replace
metadata.apiKey. See On-chain Attribution (ERC-8021).Routing fields
The recipient object may carry routing hints: this is the only channel for them on-chain, sincecreateOrder has no provider argument:
The two are mutually exclusive. A hash carrying both is not rejected: the queue wins and
providerId is ignored. A queue whose entries can’t serve the corridor is dropped silently and the order routes as unpinned; there is no on-chain rejection and no error webhook, so validate ids against a rate quote before encrypting.
Omit both and the aggregator resolves a queue itself at order creation. Entries in a multi-entry queue must name providers that can serve the corridor: active, with a live standard offer, and, for a provider restricted to specific senders, one whose list includes the sender resolved from metadata.apiKey. A one-entry queue is simply a pin.
Reading a hash the aggregator produced: queued orders publish
"ProviderID": "" plus a ProviderIDs array. Anything downstream that parses ProviderID must fall back to ProviderIDs[0]. Keys decode case-insensitively, so providerIds and ProviderIDs are equivalent on the way in.- JavaScript
- Python
- Go
- cURL
On-chain Attribution (ERC-8021)
Paycrest tags EVM transactions with an ERC-8021 schema-0 data suffix that carries a sender’s trading name as a public, human-readable attribution tag. The suffix is execution-inert: the Gateway contract ignores trailing bytes beyond its expected ABI arguments, so it passes through without affecting execution. Cost is roughly 16 gas per non-zero byte.The suffix is public attribution only. It is not read for sender identification. Sender resolution, webhook delivery, and order lookup use
metadata.apiKey inside the encrypted messageHash, which remains the authoritative and only mechanism.Who appends the suffix
On the Sender API path the aggregator appends the suffix to the transactions it submits for an order: creation, settlement, and refunds. Senders with no trading name on their KYB profile get no suffix. There is nothing to configure.
If you call the Gateway contract directly, nothing is appended for you. The rest of this section covers appending your own.
Your sender code
Pick a printable-ASCII code that identifies you publicly. Paycrest uses the trading name from the KYB profile for its own attribution, so matching that keeps your direct transactions consistent with your Sender API ones.Whatever you put in the suffix is permanently public on-chain. Use a business identifier you are happy to publish. Never place an API secret, key ID, or any credential in the suffix: your API secret stays for webhooks and REST authentication only.
Suffix layout
Schema 0, parsed backwards from the end of the calldata:
Constraints:
codes must be non-empty printable ASCII (0x20 to 0x7e), individual codes must not contain a comma (the delimiter), and the joined string must be at most 255 bytes. Violating any of these makes the suffix unparseable by ERC-8021 readers. It has no effect on your order, which is processed from metadata.apiKey either way.
Worked example for trading name AcmeCorp:
Encoding the suffix
- JavaScript
- Python
- Go
- cURL
Appending to createOrder
The suffix must be appended to the calldata before signing and gas estimation so it is covered by the signature and paid for in the gas limit. Keep sendingmetadata.apiKey: the suffix is additive, not a replacement.
Viem’s
writeContract and simulate helpers build calldata internally and give you no place to append raw bytes. To attach a suffix, encode the call yourself with encodeFunctionData and send it with sendTransaction.- JavaScript
- Python
- Go
- cURL
Where the suffix must live
ERC-8021 readers parse the outer transaction calldata backwards from its final byte, so the suffix has to be the last thing in the top-level input.- EOA senders: append to
tx.data. - Account abstraction / smart accounts: append to the outer
userOp.callData, the top-level input that lands on-chain. - Do not bury the suffix inside a nested or inner call. A suffix on an inner call is invisible to the parser, because ABI encoding pads inner
bytesfields and the outer calldata will not end with the marker.
Codes and the Base Builder Code
Thecodes field is a list, so a transaction can carry more than one code, comma-joined. For direct integrators the default is your own code alone, on every EVM network including Base.
bc_julg9gbq is Noblocks’ registered Base Builder Code. Don’t include it in your own transactions.Relationship to metadata.apiKey
metadata.apiKey is unchanged, not deprecated, and remains the single mechanism by which the aggregator identifies the sender behind an order. Keep sending it exactly as before.
Appending a suffix does not replace
metadata.apiKey. An order created with a suffix but without metadata.apiKey will not be linked to your sender profile, and you will not receive webhooks for it.Network support
On-chain attribution applies to EVM networks only. References: ERC-8021 specification · erc8021.com · Base: Builder Codes & ERC-8021Token Approval
- JavaScript
- Python
- Go
- cURL
Get Order Information
- JavaScript
- Python
- Go
- cURL
Event Listening
- JavaScript
- Python
- Go
- cURL
Error Handling
- JavaScript
- Python
- Go
- cURL
Complete Example
- JavaScript
- Python
- Go
- cURL
Supported Networks
- Ethereum: USDT, USDC, cNGN
- Base: USDT, USDC, cNGN (primary recommended network)
- Arbitrum One: USDT, USDC
- Polygon: USDT, USDC, cNGN
- BNB Smart Chain: USDT, USDC, cNGN
- Celo: USDT, USDC, cNGN
Paycrest supports very low minimum orders ($0.50) and uses cost-effective EVM L2s. Start with small amounts to test your integration before scaling up.
Failed transactions still consume gas. Validate all parameters before submitting transactions.