Relayer V3 - XOXNO Docs

Use Relayer V3 when the user signs a transaction with a relayer field and XOXNO co-signs, pays gas, and broadcasts it.

Availability

Relayer V3 is gated access. Your app must be approved before relay or POST /v1/sign succeeds.

Broadcast Vs Relay

Action	Who signs	Who pays gas	Use when
`broadcast`	User or backend signer	User	You already have a fully signed transaction.
`relay`	User first, XOXNO second	XOXNO	Your approved integration sponsors the user’s gas.

Flow

Derive sender shard

Compute the sender shard from the bech32 public key and select the matching Relayer address.

Build transaction with relayer

Set the transaction relayer field before the user signs.

User signs

The user signature must cover the transaction body including relayer.

Relay

Send the relay control message or call POST /v1/sign. The Relayer validates shard match, co-signs, and broadcasts.

Verify

Track the returned hash with tx-status/{hash} or Gateway status.

Do not add the relayer field after user signing. That changes the signed payload and invalidates the signature.

Shard Relayer Addresses

Shard	Relayer address
0	`erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h`
1	`erd12yxd5phejzw83gn8qh6jfz6q9a0ekyyhkfd3c49r03mxw25l3a5swq3nf7`
2	`erd13jxp0yjh7gjvzgrg5mj7e8rzhn5lzcye45l0p6e5996d543r7vrq9e50za`

Using a Relayer address from the wrong shard returns shard mismatch. Derive the sender shard before building the transaction.

Required Transaction Fields

Field	Requirement
`sender`	User bech32 address.
`receiver`	Target account or contract.
`gasPrice`	Minimum `1000000000`. The Relayer pays the fee after co-signing.
`gasLimit`	Must cover execution.
`signature`	User signature over the transaction including `relayer`.
`relayer`	Shard-matched Relayer address.

Example Relay Payload

{
  "action": "relay",
  "requestId": "relay-001",
  "tx": {
    "nonce": 42,
    "value": "0",
    "receiver": "erd1contract...",
    "sender": "erd1user...",
    "gasPrice": 1000000000,
    "gasLimit": 50000,
    "data": "c3dhcA==",
    "chainID": "1",
    "version": 2,
    "signature": "<user-signature>",
    "relayer": "erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h"
  }
}

The payload above is an example. Replace placeholders with a transaction signed by the user after relayer was set.

Common Failures

Symptom	Cause	Fix
`shard mismatch`	Sender shard and Relayer address shard differ.	Select the Relayer address for the sender shard.
`invalid signature`	User signed before `relayer` was added, or payload changed.	Rebuild and ask the user to sign again.
`unauthorized app`	Integration is not approved for Relayer V3.	Request access before shipping the flow.
`signing capacity exceeded`	Signing queue is full.	Back off and retry.

​Availability

​Broadcast Vs Relay

​Flow

​Shard Relayer Addresses

​Required Transaction Fields

​Example Relay Payload

​Common Failures

​Related Pages

Availability

Broadcast Vs Relay

Flow

Shard Relayer Addresses

Required Transaction Fields

Example Relay Payload

Common Failures

Related Pages