> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Relayer V3

> Use Relayer V3 when XOXNO co-signs a user-signed MultiversX transaction and pays gas.

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

<Steps>
  <Step title="Derive sender shard">
    Compute the sender shard from the bech32 public key and select the matching Relayer address.
  </Step>

  <Step title="Build transaction with relayer">
    Set the transaction `relayer` field before the user signs.
  </Step>

  <Step title="User signs">
    The user signature must cover the transaction body including `relayer`.
  </Step>

  <Step title="Relay">
    Send the `relay` control message or call `POST /v1/sign`. The Relayer validates shard match, co-signs, and broadcasts.
  </Step>

  <Step title="Verify">
    Track the returned hash with `tx-status/{hash}` or Gateway status.
  </Step>
</Steps>

<Warning>
  Do not add the `relayer` field after user signing. That changes the signed payload and invalidates the signature.
</Warning>

## Shard Relayer Addresses

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

<Warning>
  Using a Relayer address from the wrong shard returns `shard mismatch`. Derive the sender shard before building the transaction.
</Warning>

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

```json theme={"system"}
{
  "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.                              |

## Related Pages

* [WebSocket relay action](/api-reference/ws/relay)
* [WebSocket lifecycle](/relayer/websocket-lifecycle)
* [Broadcasting](/relayer/transaction-broadcasting)
* [Transaction status tracking](/relayer/tx-status-tracking)