Skip to content

Decentralized Finance (DeFi) Payload Formats

This page provides the required JSON payload formats for signing operations across different blockchain ecosystems.

For sign contract data API endpoint reference

EVM-compatible chains (Ethereum, Polygon, BSC, Avalanche, etc.) support two signature types:

V4 (EIP-712 Typed Data Signing)

EIP-712 allows for structured data signing with domain separation.

{
  "domain": {
    "chainId": "5",
    "name": "Ether Mail",
    "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC",
    "version": "1"
  },
  "message": {
    "contents": "Hello, Bob!",
    "from": {
      "name": "Cow",
      "wallets": [
        "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826",
        "0xDeaDbeefdEAdbeefdEadbEEFdeadbeEFdEaDbeeF"
      ]
    },
    "to": [
      {
        "name": "Bob",
        "wallets": [
          "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB",
          "0xB0BdaBea57B0BDABeA57b0bdABEA57b0BDabEa57",
          "0xB0B0b0b0b0b0B000000000000000000000000000"
        ]
      }
    ]
  },
  "primaryType": "Mail",
  "types": {
    "EIP712Domain": [
      {"name": "name", "type": "string"},
      {"name": "version", "type": "string"},
      {"name": "chainId", "type": "uint256"},
      {"name": "verifyingContract", "type": "address"}
    ],
    "Group": [
      {"name": "name", "type": "string"},
      {"name": "members", "type": "Person[]"}
    ],
    "Mail": [
      {"name": "from", "type": "Person"},
      {"name": "to", "type": "Person[]"},
      {"name": "contents", "type": "string"}
    ],
    "Person": [
      {"name": "name", "type": "string"},
      {"name": "wallets", "type": "address[]"}
    ]
  }
}

FieldDescription
domainDefines the signing domain (chain ID, contract, version)
messageThe actual data being signed
primaryTypeThe main type being signed
typesType definitions for structured data

For more details on EIP-712, refer to MetaMask's official documentation.

personalSign

Simple message signing for arbitrary strings.

{
  "message": "0x2ca3vaa3....."
}
Field Description
message Hexadecimal string of the message to sign

Usage Example

// Personal Sign
const evmPayload = {
  address: "0x115eb8585ad0cfA18e1b7Fd39Dfc5c655adF8fB8",
  signature_version: "personalSign",
  payload: {
    message: "0x48656c6c6f20576f726c64" // "Hello World" in hex
  },
  chain: "ETH",
  order_no: "SIGN001",
  description: "Sign message"
};

await signContract(evmPayload);

Bitcoin signing supports three different operations:

signMessage

Sign arbitrary text messages.

{
  "text": "hello world~"
}
Field Description
text The plain text message to sign

signPsbt / signPsbts

Sign one or more Partially Signed Bitcoin Transactions (PSBT).

[
  {
    "id": 1,
    "options": {
      "auto_finalized": false,
      "to_sign_inputs": [
        {
          "index": 0,
          "address": null,
          "public_key": "03b7d09ec077ecdd4dd50c21d68637f0f2bc8f32e8973a7456924308eeba4ecf13",
          "sighash_types": null,
          "disable_tweak_signer": false
        }
      ]
    },
    "rawtx": null,
    "dapp": "https://stake2.dev.btcs.network/my-staking#btc",
    "psbt_hex": "70736274ff010052020000000160aa1a9123351f1a74ba04f861693c0d894cb299ada7170844a3fae53b1643e90000000000feffffff01a5b40d0000000000160014c3fcec007e97b22d72859fb900f8aafe87d676a6d31736670001012b40420f0000000000220020bc30954e24a0f54e027f0d9d8203b1e8304873ce40dfb9eda40e28e8f6bbf20401052004d3173667b17576a914c3fcec007e97b22d72859fb900f8aafe87d676a688ac0000",
    "signed_psbt_hex": null
  }
]
Field Description
id Transaction identifier
options.auto_finalized Whether to automatically finalize the transaction
options.to_sign_inputs Array of inputs to sign
options.to_sign_inputs[].index Input index to sign
options.to_sign_inputs[].public_key Public key for signing
options.to_sign_inputs[].sighash_types Signature hash types (optional)
psbt_hex The PSBT in hexadecimal format
dapp The dApp URL requesting the signature

signPsbt is for signing a single transaction, while signPsbts allows signing multiple transactions in one call.

Usage Example

// Sign Message
const btcPayload = {
  address: "tb1pkhduwswuk7qhx77djyt730dp77tjrc8ullftfyr2deaa635d55ns04zext",
  signature_version: "signMessage",
  payload: {
    text: "Verify ownership of this address"
  },
  chain: "BTC",
  order_no: "SIGN002"
};

await signContract(btcPayload);

Cosmos-based chains support three signature types:

signAmino

Legacy JSON transaction signing (backwards compatible).

{
  "account_number": "123",
  "chain_id": "cosmoshub-4",
  "fee": {
    "amount": [
      { "denom": "uatom", "amount": "1000" }
    ],
    "gas": "200000"
  },
  "memo": "Test transaction",
  "msgs": [
    {
      "type": "cosmos-sdk/MsgSend",
      "value": {
        "from_address": "cosmos1...",
        "to_address": "cosmos1...",
        "amount": [
          { "denom": "uatom", "amount": "1000000" }
        ]
      }
    }
  ],
  "sequence": "42"
}
Field Description
account_number The account number on the blockchain
chain_id The chain identifier
fee Transaction fee details
msgs Array of messages to execute
sequence Account sequence number

signDirect

Modern Protobuf transaction signing (recommended for new implementations).

{
  "body": {
    "messages": [
      {
        "@type": "/cosmos.bank.v1beta1.MsgSend",
        "from_address": "cosmos1...",
        "to_address": "cosmos1...",
        "amount": [
          { "denom": "uatom", "amount": "1000000" }
        ]
      }
    ],
    "memo": "Test transaction",
    "timeout_height": "0",
    "extension_options": [],
    "non_critical_extension_options": []
  },
  "auth_info": {
    "signer_infos": [
      {
        "public_key": {
          "@type": "/cosmos.crypto.secp256k1.PubKey",
          "key": "A3..."
        },
        "mode_info": {
          "single": {
            "mode": "SIGN_MODE_DIRECT"
          }
        },
        "sequence": "42"
      }
    ],
    "fee": {
      "amount": [
        { "denom": "uatom", "amount": "1000" }
      ],
      "gas_limit": "200000",
      "payer": "",
      "granter": ""
    }
  },
  "chain_id": "cosmoshub-4",
  "account_number": "123"
}
Field Description
body Transaction body containing messages
auth_info Authentication information including signer details
chain_id The chain identifier
account_number The account number

signArbitrary

Sign arbitrary data or messages (not necessarily a transaction).

{
  "chain_id": "cosmoshub-4",
  "account_number": "123",
  "sequence": "42",
  "fee": {
    "amount": [],
    "gas": "0"
  },
  "msgs": [
    {
      "type": "sign/MsgSignData",
      "value": {
        "signer": "cosmos1...",
        "data": "VGhpcyBpcyBhIHRlc3QgbWVzc2FnZQ=="
      }
    }
  ],
  "memo": ""
}
Field Description
msgs Contains the MsgSignData message
msgs[].value.data Base64 encoded arbitrary data to sign
msgs[].value.signer The address of the signer

The data field in signArbitrary must be Base64 encoded.

Usage Example

// Sign Amino
const cosmosPayload = {
  address: "cosmos1qqp3t4zhpwxp8sjq9j7p42flf4z5r0u9ex7n3k",
  signature_version: "signAmino",
  payload: {
    account_number: "123",
    chain_id: "cosmoshub-4",
    fee: {
      amount: [{ denom: "uatom", amount: "1000" }],
      gas: "200000"
    },
    memo: "Test transaction",
    msgs: [/* ... */],
    sequence: "42"
  },
  chain: "COSMOS",
  order_no: "SIGN003"
};

await signContract(cosmosPayload);

Summary of the various supported signature version

Chain TypeSignature VersionUse Case
EVMV4Structured data signing (EIP-712)
personalSignSimple message signing
BTCsignMessageMessage signing only
signPsbtSingle transaction signing
signPsbtsMultiple transaction signing
CosmossignAminoLegacy JSON transactions
signDirectModern Protobuf transactions
signArbitraryArbitrary data signing