> For the complete documentation index, see [llms.txt](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/actions/ramp.md).

# 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:

```json
[
  {
    "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) |
| `abiURL`  | Yes      | Full ABI fragment for the method (if not already known by WalletTwo) |

***

### 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

```js
const additionalTxns = JSON.stringify([
  {
    method: "mint",
    params: ["0xUserAddress", "1000000000000000000"],
    address: "0xYourContractAddress",
    abiURL: "https://example.com/abi"
  }
]);

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

```html
<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.