Transaction Authorization
Sign payouts with the user's wallet when your company runs in Signature mode.
Before You Start
Read the following guides before proceeding:
| Guide | Why |
|---|---|
| Api Basics | Required headers and request configuration |
| Authentication | The user token that identifies the signer |
| Environments | GET /api/v1/config returns your company's authorization mode |
Overview
Every company runs in one of two transaction authorization modes, set by Wirex per company.
| Mode | Payouts |
|---|---|
External (default) | Executed without a wallet signature. You authorize the user yourself before calling the API |
Signature | Each payout carries transaction_authorization: a signature by the user's wallet over a fixed sentence that names the operation, the estimation and a nonce |
A refused signature moves no funds and spends no estimation.
Reading the Mode
GET /api/v1/config
Without a user token, send your company id (UUID) in X-Company-Id.
{
"defaultCompanyId": "00000000-0000-0000-0000-000000000044",
"transactionAuthorizationMode": "External"
}Read the mode once at startup and branch on it.
Endpoints
| Method | Path | Operation | Signature |
|---|---|---|---|
POST | /api/v1/bank/transfer | BankTransfer | Required in Signature mode — see SEPA Bank Transfer and ACH Bank Transfer |
POST | /api/v3/bank/initiate/{corridor} | CorridorTransferInitiate | Required in Signature mode, on every corridor — see Corridor Transfers |
POST | /api/v1/cards/transfer | CardTransfer | Required in Signature mode — see Card Transfer |
POST | /api/v2/recipients | RecipientCreate | Optional. Verified only for agent companies in Signature mode; otherwise only its shape is checked — see Create Recipients |
The signer is the user's wallet — the address Wirex resolves for the authenticated user (on EVM, the EOA, not the Smart Wallet).
The transaction_authorization Object
transaction_authorization Object{
"transaction_authorization": {
"message_signature": "0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac81f0c5b0e4a7c1d2e3f405162738495a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c1b",
"nonce": 1704103200
}
}| Field | Type | Required | Description |
|---|---|---|---|
transaction_authorization | object | Conditional | Required on the payout endpoints in Signature mode |
transaction_authorization.message_signature | string | Yes | Signature over the sentence. Encoding per chain in Signing |
transaction_authorization.nonce | integer (int64) | Yes | The Unix time, in seconds, at which the sentence was formed. Not 0, not more than 5 minutes old, not more than 60 seconds in the future |
transaction_authorization.public_key | string | Conditional | XRPL wallets only: the signer's public key in hex |
Each signature is accepted once, even when the execution behind it fails. A retry needs a new nonce and a
new signature.
The Sentence
Every character of the sentence is signed. Build it from the request you are about to send.
Payouts
I confirm that I'm executing <operation> according to estimation <estimation_id> at <nonce>
| Placeholder | Value |
|---|---|
<operation> | BankTransfer, CorridorTransferInitiate or CardTransfer, from the Endpoints table |
<estimation_id> | The request's estimation_id as a lowercase, hyphenated UUID |
<nonce> | The same integer as transaction_authorization.nonce |
Example, for POST /api/v3/bank/initiate/sepa with estimation_id 00000000-0000-0000-0000-000000000001
and nonce 1704103200:
I confirm that I'm executing CorridorTransferInitiate according to estimation 00000000-0000-0000-0000-000000000001 at 1704103200
Recipient Creation
I confirm I save recipient <name> <details> at <nonce>
<name> is company_name for a business, first_name + space + last_name for an individual, and
nick_name for a CrossChainCrypto recipient or a Crypto recipient without names.
<details>, by payment detail type:
type | <details> |
|---|---|
Sepa | IBAN <iban> BIC <bic> — both upper-cased, with every space removed |
Ach | account number <account_number> routing number <routing_number> |
Fedwire | account number <account_number> routing number <routing_number> — the same sentence as Ach |
Crypto | address <address> on <network> — an EVM address in its EIP-55 checksum form |
CrossChainCrypto | address <address> on <network> — a 0x address is written in EIP-55 form when network is EVM, and as sent otherwise. tag must be empty |
Card | card ending <card_pan_last> with id <card_id> |
Other types are not covered on this page; create them without transaction_authorization.
Example, for an individual SEPA recipient:
I confirm I save recipient Alex Grey IBAN DE89370400440532013000 BIC COBADEFF at 1704103200
Signing
| Wallet | Signature |
|---|---|
| EVM EOA | EIP-191 personal_sign over the sentence, hex-encoded with 0x. v may be 27/28 or 0/1 |
| EVM smart-contract wallet | ERC-1271 isValidSignature over the EIP-191 hash |
| Stellar | ed25519 over the SHA-256 digest of the sentence, base64-encoded |
| XRPL | ed25519 or secp256k1 over the sentence, hex-encoded. Send the signer's public_key; the address derived from it must be the user's address |
// EVM, with viem
const nonce = Math.floor(Date.now() / 1000);
const message = `I confirm that I'm executing CorridorTransferInitiate according to estimation ${estimationId} at ${nonce}`;
const messageSignature = await walletClient.signMessage({ account: userEoaAddress, message });
const response = await fetch(`${baseUrl}/api/v3/bank/initiate/sepa`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'X-User-Wallet': userEoaAddress,
'X-Chain-Id': chainId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
estimation_id: estimationId,
source_token_address: tokenAddress,
transaction_authorization: { message_signature: messageSignature, nonce }
})
});# EVM, with eth-account
import time
from eth_account import Account
from eth_account.messages import encode_defunct
nonce = int(time.time())
message = f"I confirm that I'm executing CorridorTransferInitiate according to estimation {estimation_id} at {nonce}"
signed = Account.sign_message(encode_defunct(text=message), private_key=user_private_key)
response = requests.post(
f"{base_url}/api/v3/bank/initiate/sepa",
headers={
"Authorization": f"Bearer {access_token}",
"X-User-Wallet": user_eoa_address,
"X-Chain-Id": chain_id,
"Content-Type": "application/json"
},
json={
"estimation_id": estimation_id,
"source_token_address": token_address,
"transaction_authorization": {
"message_signature": "0x" + signed.signature.hex().removeprefix("0x"),
"nonce": nonce
}
}
)// EVM, with go-ethereum
nonce := time.Now().Unix()
message := fmt.Sprintf("I confirm that I'm executing CorridorTransferInitiate according to estimation %s at %d", estimationId, nonce)
signature, _ := crypto.Sign(accounts.TextHash([]byte(message)), userPrivateKey)
signature[64] += 27
body, _ := json.Marshal(map[string]interface{}{
"estimation_id": estimationId,
"source_token_address": tokenAddress,
"transaction_authorization": map[string]interface{}{
"message_signature": hexutil.Encode(signature),
"nonce": nonce,
},
})
req, _ := http.NewRequest("POST", baseURL+"/api/v3/bank/initiate/sepa", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("X-User-Wallet", userEoaAddress)
req.Header.Set("X-Chain-Id", chainId)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()Sign as close to the call as possible: the nonce is valid for 5 minutes.
Error Handling
{
"error_reason": "ErrorPermissionDenied",
"error_description": "transaction authorization does not authorize this request",
"error_category": {
"category": "CategoryUnauthorized",
"http_status_code": 401
}
}Signature errors are 401, malformed transaction_authorization is 400.
| Error Reason | Status | Description | Resolution |
|---|---|---|---|
ErrorMissingField | 401 | transaction authorization is required | Signature mode: sign and send it |
ErrorExpired | 401 | transaction authorization has expired | nonce older than 5 minutes. Sign again |
ErrorNotYetValid | 401 | transaction authorization is not yet valid, check the device clock | nonce more than 60 seconds in the future. Check the signing device's clock |
ErrorPermissionDenied | 401 | transaction authorization does not authorize this request | The sentence or signer does not match the request. Rebuild the sentence and sign again |
ErrorAlreadyExists | 401 | transaction authorization has already been used | Sign again with a new nonce |
ErrorMissingField / ErrorInvalidField | 400 | Missing message_signature or nonce, undecodable signature, or (agent companies) an unsignable recipient type | Fix the field named in error_details |
ErrorGeneral | 503 | Transaction authorization is temporarily unavailable | Nothing was executed. Retry with a new signature |
Updated 1 day ago

