# Signing transfers

> The exact transfer message format, and the rules the network applies before it accepts a signature.

A USD Network transfer is authorised by an EIP-191 `personal_sign` signature over a short plain-text message. Wallets show the message as it is, so the person signing can read exactly what they are approving.

## The message

```text title="Message"
USD Network transfer
Chain: usdnet-testnet-1
From: 0x1323a980c3e4736108741dacdad57d08e60bd827
To: 0x38496f6877382de8255668ae407f4c0ea2acc0f7
Amount: 12.5 USDT
Fee: 0.01 USDT
Nonce: 0
Memo: Hello from the docs
```

Lines are joined with a single newline (`\n`), with no trailing newline.

| Line | Rule |
| --- | --- |
| `USD Network transfer` | Fixed header |
| `Chain:` | The chain ID. A signature for one chain is not valid on another. |
| `From:` | Sender address, lowercase |
| `To:` | Recipient address, lowercase, different from the sender |
| `Amount:` | Decimal amount followed by ` USDT`, up to 6 decimals, written exactly as in the request body |
| `Fee:` | Must be `0.01 USDT` |
| `Nonce:` | The sender's current nonce |
| `Memo:` | Optional. Omit the whole line when there is no memo. Up to 140 characters. |

> [!WARNING]
> The network rebuilds the message from the fields you submit. If `amount` in the body is `"12.50"` but you signed `Amount: 12.5 USDT`, the signature will not match. Use the same string in both places.

## Submitting

```json title="POST /tx"
{
  "from": "0x1323a980c3e4736108741dacdad57d08e60bd827",
  "to": "0x38496f6877382de8255668ae407f4c0ea2acc0f7",
  "amount": "12.5",
  "fee": "0.01",
  "nonce": 0,
  "memo": "Hello from the docs",
  "sig": "0x2c96fda2…1ca36b3b0b1c"
}
```

## What the network checks

1. Both addresses are valid `0x…` addresses and are different.
2. The amount is a positive decimal with at most 6 decimals, and the fee is `0.01`.
3. The signature recovers to `from`.
4. Neither address is frozen.
5. The nonce equals the sender's current nonce.
6. The balance covers the amount plus the fee.

Checks 4 to 6 run again when the transfer is sealed, against the balances at that moment.

## Transfer hash

The transfer `hash` is `0x` followed by the SHA-256 of the canonical JSON (keys sorted, no whitespace, absent fields omitted) of the chain ID, type, addresses, amount, fee, nonce, memo, time and signature (plus `source` and `attest` on bridge events). The `time` is set by the network when it accepts the transfer, so the hash is known only once the transfer is submitted. It identifies the transfer on the explorer and in blocks.

## Signing in other languages

Any library that implements EIP-191 works. In ethers: `await wallet.signMessage(message)`. In web3.py: `Account.sign_message(encode_defunct(text=message), key)`. From a browser wallet: `ethereum.request({ method: 'personal_sign', params: [message, from] })`.
