> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Transaction Fee
> Calculates the fee for a given transaction type, currency, and amount.
Calculate the fee for a given transaction type, currency, and amount before executing the transaction.
## Example Request
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/fee" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"currency": "NGN",
"transactionType": "withdrawal",
"amount": 5000
}'
```
## Example Response
```json theme={null}
{
"status": 200,
"success": true,
"message": "Transaction fee retrieved successfully",
"data": {
"fee": {
"amount": 50,
"currency": "NGN"
}
}
}
```
## Parameters
| Parameter | Type | Required | Description |
| --------------------- | ------------- | -------- | ---------------------------------------------------------------------------- |
| `currency` | string | Yes | 3-letter code of the wallet being debited |
| `transactionType` | string | Yes | `deposit`, `withdrawal`, or `swap` |
| `amount` | number | Yes | Amount in the smallest unit (kobo for NGN, cents for USD) |
| `recipientCurrency` | string | No | For FX payouts — the currency the beneficiary receives |
| `withdrawal_method` | string | No | The payout rail to price — see below |
| `destination_country` | string | No | 2-letter country code of the destination bank |
| `beneficiaryId` | string (UUID) | No | Quote a saved beneficiary; the rail and destination country are read from it |
***
## Quoting a specific withdrawal method
Fees are configured **per rail**, so an ACH and a wire to the same bank are usually priced differently. Pass `withdrawal_method` to quote the rail you will actually send on:
| `withdrawal_method` | Rail |
| ----------------------------- | ------------------------------------------------------------ |
| `ach` | Domestic US ACH — settles in business days, cheapest US rail |
| `domestic_wire` | Domestic US wire (Fedwire) — same-day, priced above ACH |
| `international_wire` | Cross-border wire (SWIFT) |
| `local_transfer` | In-country transfer (e.g. NGN bank transfer) |
| `crypto_usdt` / `crypto_usdc` | Stablecoin payout |
| `mobile_money` | Mobile money payout |
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/fee" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"transactionType": "withdrawal",
"amount": 100000,
"withdrawal_method": "ach",
"destination_country": "US"
}'
```
Swap `"ach"` for `"domestic_wire"` or `"international_wire"` to compare rails before deciding which to send on — everything else in the request stays the same.
Omitting `withdrawal_method` quotes the currency-level fee, which may not be what the withdrawal is charged if a rail-specific fee applies to your account. Always send the rail you intend to use.
***
## Quoting a saved beneficiary
If you are paying a saved beneficiary, pass `beneficiaryId` instead and the rail and destination country are taken from that beneficiary — no need to restate them:
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/fee" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"transactionType": "withdrawal",
"amount": 100000,
"beneficiaryId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}'
```
Anything you send explicitly wins over the beneficiary's own values, so you can quote a different rail for an existing beneficiary by supplying `withdrawal_method` alongside `beneficiaryId`.
The beneficiary must belong to your account. An unknown `beneficiaryId` returns a `400` rather than falling back to a default fee — a quote never silently prices a different rail than the withdrawal will use.
***
## FX payouts
For a cross-currency payout, add `recipientCurrency`. The response then also carries `feeInRecipientCurrency`:
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/fee" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"transactionType": "withdrawal",
"amount": 100000,
"recipientCurrency": "NGN"
}'
```
Call this endpoint before initiating a withdrawal or swap to show your users the exact fee they'll be charged. Send the same `withdrawal_method` (or `beneficiaryId`) you will send to [`POST /wallet/withdraw`](/api-reference/endpoint/wallet/withdraw) so the quote matches the charge.
## OpenAPI
````yaml POST /wallet/fee
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/wallet/fee:
post:
summary: Get Transaction Fee
description: Calculates the fee for a given transaction type, currency, and amount.
operationId: getTransactionFee
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionFeeRequest'
responses:
'200':
description: Fee calculated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Transaction fee retrieved successfully
data:
type: object
properties:
fee:
type: object
properties:
amount:
type: number
description: Fee in the smallest unit of the source currency
example: 50
currency:
type: string
description: >-
Currency the fee is charged in (the wallet being
debited)
example: NGN
feeInRecipientCurrency:
type: number
description: >-
Present only for FX quotes — the same fee
expressed in recipientCurrency
example: 75000
'400':
description: Bad request - Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
TransactionFeeRequest:
type: object
required:
- currency
- transactionType
- amount
properties:
currency:
type: string
description: 3-letter currency code
minLength: 3
maxLength: 3
example: NGN
transactionType:
type: string
enum:
- deposit
- withdrawal
- swap
description: Type of transaction
amount:
type: number
description: >-
Transaction amount in the smallest unit (kobo for NGN, cents for
USD)
example: 5000
recipientCurrency:
type: string
description: >-
For FX payouts — the currency the beneficiary receives. The response
then also carries feeInRecipientCurrency.
minLength: 3
maxLength: 3
example: NGN
withdrawal_method:
type: string
description: >-
Payout rail to price. Fees are configured per rail, so an ACH and a
wire to the same bank are usually priced differently — send the rail
you will actually withdraw on. Omitted, the currency-level fee is
quoted.
enum:
- ach
- domestic_wire
- international_wire
- local_transfer
- crypto_usdt
- crypto_usdc
- rolla_transfer
- mobile_money
example: ach
destination_country:
type: string
description: >-
2-letter country code of the destination bank, for fees scoped to a
corridor.
minLength: 2
maxLength: 2
example: US
beneficiaryId:
type: string
format: uuid
description: >-
Quote a saved beneficiary. withdrawal_method and destination_country
are read from it when not supplied explicitly. An id that does not
belong to your account returns a 400.
example: c3d4e5f6-a7b8-9012-cdef-123456789012
Error:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````