Ramp

Endpoint: /action/ramp

Embeds the WalletTwo ramp flow inside your application. The ramp lets a logged-in user buy, sell, or swap tokens using fiat or crypto payment methods. All ramp logic is handled by the RampProvider component; this action is purely the entry point that reads URL parameters and passes them in.

---

Required user state

Check	Middleware	Redirects to if missing
User is logged in	LoggedMiddleware	/auth/login
Email is verified	EmailVerifiedMiddleware	/auth/email/verify
Wallet is created	WalletMiddleware	/auth/wallet/register

---

Iframe URL

https://<WALLETTWO_ORIGIN>/action/ramp?iframe=true

All parameters are optional and configure the initial state of the ramp flow:

Param	Maps to	Type	Description
ctrt	_contract	string	Contract address to use for the operation
amt	_amount	string	Pre-filled amount
pm	_paymentMethod	string	Pre-selected payment method
cur	_currency	string	Pre-selected currency code (e.g. USD, EUR)
op	_operator	string	Operator identifier
ntwk	_chainId	number	Chain ID of the target network
ext_id	_externalId	string	Your external reference ID (correlates the ramp session to your own records)
redirect_uri	_redirectUrl	string	URL to redirect the iframe to when the ramp flow completes
use_fiat	useFiat	"true" | "false"	Whether to use the fiat onramp flow. Defaults to true
additional_txns	_additionalTransactions	JSON string	Array of additional transactions to execute alongside the ramp (see below)
iframe	(layout)	"true"	Activates bare rendering mode

---

Additional transactions (additional_txns)

additional_txns is a JSON-encoded array of transaction objects to be bundled with the ramp operation. Parse errors are swallowed silently; if the JSON is invalid, additional_txns defaults to [].

Expected format:

[
  {
    "method": "<contract-method-name>",
    "params": ["<param1>", "<param2>"],
    "address": "<contract-address>",
    "network": "<network-identifier>",
    "abi": {},
    "wait_tx": true
  }
]

Field	Required	Description
method	Yes	Name of the contract method to call
params	Yes	Array of arguments for the method
address	Yes	Target contract address
network	Yes	Network/chain identifier
abi	No	Full ABI fragment for the method (if not already known by WalletTwo)
wait_tx	No	Whether to wait for on-chain confirmation. Defaults to true

---

What happens when the action runs

1. URL params are read immediately.

2. If additional_txns is present it is JSON-parsed; errors are caught and logged.

3. The view waits for selectedNetwork from the network hook. While waiting, a full-screen spinner is shown.

4. Once the network is available, RampProvider mounts with all mapped props and drives the rest of the flow.

---

Loading state

While the selected network is not yet available, the iframe renders only:

[centered spinner]

This is normal. It resolves as soon as the app's network state is hydrated.

---

Example URLs

Minimal (fiat onramp, defaults)

https://<WALLETTWO_ORIGIN>/action/ramp?iframe=true

Pre-fill fiat EUR purchase on Polygon

https://<WALLETTWO_ORIGIN>/action/ramp?iframe=true&cur=EUR&ntwk=137&use_fiat=true&redirect_uri=https%3A%2F%2Fexample.com%2Framp-done

Crypto-only, with external reference ID

https://<WALLETTWO_ORIGIN>/action/ramp?iframe=true&use_fiat=false&ext_id=order_8821&redirect_uri=https%3A%2F%2Fexample.com%2Framp-done

With additional bundled transaction

const additionalTxns = JSON.stringify([
  {
    method: "mint",
    params: ["0xUserAddress", "1000000000000000000"],
    address: "0xYourContractAddress",
    network: "137",
    wait_tx: true
  }
]);

const url = new URL("https://<WALLETTWO_ORIGIN>/action/ramp");
url.searchParams.set("iframe", "true");
url.searchParams.set("ntwk", "137");
url.searchParams.set("additional_txns", additionalTxns);
url.searchParams.set("redirect_uri", "https://example.com/ramp-done");

---

Host page integration

<iframe
  id="w2-ramp"
  src="https://<WALLETTWO_ORIGIN>/action/ramp?iframe=true&cur=EUR&ntwk=137"
  style="width:420px;height:700px;border:0;"
  allow="clipboard-read; clipboard-write; payment"
></iframe>

The ramp component manages its own navigation states internally. Result handling (success, failure, cancellation) is controlled by redirect_uri or by events fired from RampProvider. Consult the RampProvider documentation for the full event contract emitted during the ramp flow.

---

Notes

• The ntwk param is cast to Number. Passing a non-numeric value results in undefined being passed to RampProvider, which falls back to its own default network.

• If use_fiat is not provided, it defaults to true.

• ext_id is your reference identifier and is passed through to WalletTwo's records unchanged so you can correlate ramp sessions from your backend.