Firma Web3

Firma mensajes, datos tipados y transacciones en redes EVM y Solana.

Habilita Web3 Signing en la billetera antes de usar estos endpoints o el SDK. Está deshabilitado de forma predeterminada; las solicitudes de firma devuelven 403 Forbidden hasta que se habilite. Consulta Habilitar la firma Web3.

Las solicitudes de firma requieren aprobación antes de ejecutarse. Revísalas en Approval → DApp Transaction en el dashboard. Consulta Aprobaciones de firma Web3.

Las solicitudes devuelven un transaction_id. Consulta el endpoint de estado hasta que la firma se complete o falle.

Solicitar una firma

POST
/web3/{wallet_id}/sign

Firma un mensaje de EVM o Solana. Consulta API keys para la autenticación.

El SDK requiere una billetera y un proveedor RPC para firmar en EVM. Consulta automáticamente hasta obtener la firma.

Parámetros

  • Name
    wallet_id
    Type
    string
    Description

    ID de la billetera en la ruta de la URL.

  • Name
    method
    Type
    string
    Description

    eth_sign, eth_signTypedData_v4 o solana_signMessage.

  • Name
    message
    Type
    string
    Description

    Mensaje que se firmará. Usa un string vacío para datos tipados.

  • Name
    chain_id
    Type
    number
    Description

    ID de cadena EVM. Usa 0 para Solana.

  • Name
    typed_data
    Type
    string
    Description

    Obligatorio para firmar datos tipados. String JSON que contiene domain, types y message.

  • Name
    X-Idempotency-Key
    Type
    string
    Recommended
    recommended
    Description

    Reutiliza la misma clave al reintentar una solicitud. Actualmente, el SDK no asigna options.idempotencyKey a este header.

Respuesta

  • Name
    transaction_id
    Type
    string
    Description

    ID de la solicitud para consultar el estado de la firma.

Request

POST
/web3/:wallet_id/sign
import { EtherSigner, Environment } from '@fystack/sdk'
import { JsonRpcProvider } from 'ethers'

const provider = new JsonRpcProvider(process.env.RPC_URL!)
const signer = new EtherSigner(
  {
    apiKey: process.env.API_KEY!,
    apiSecret: process.env.API_SECRET!,
  },
  Environment.Production,
  provider,
)

signer.setWallet('YOUR_WALLET_ID')
const signature = await signer.signMessage('Authorize this session')

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87"
}

Obtener el estado de la firma

GET
/web3/{wallet_id}/sign/{transaction_id}

Obtén el estado y la firma de una solicitud de firma.

  • Name
    transaction_id
    Type
    string
    Description

    ID de la solicitud de firma.

  • Name
    status
    Type
    string
    Description

    pending_approval, pending, completed, confirmed, failed o rejected.

  • Name
    signature
    Type
    string
    Description

    Firma, cuando está disponible. Los signers del SDK para EVM esperan el estado confirmed con una firma.

  • Name
    approvals
    Type
    array
    Description

    Registros con user_id y status: pending, approved o rejected.

  • Name
    created_at
    Type
    string
    Description

    Timestamp de creación.

  • Name
    updated_at
    Type
    string
    Description

    Timestamp de la última actualización.

Si se agota el tiempo de consulta, revisa la solicitud existente antes de enviar otra.

Request

GET
/web3/:wallet_id/sign/:transaction_id
import { APIService, Environment } from '@fystack/sdk'

const api = new APIService(
  { apiKey: process.env.API_KEY!, apiSecret: process.env.API_SECRET! },
  Environment.Production,
)

const status = await api.getSignStatus('YOUR_WALLET_ID', 'TRANSACTION_ID')
console.log(status.signature)

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87",
  "status": "pending_approval",
  "approvals": [],
  "created_at": "2026-10-03T00:00:00Z",
  "updated_at": "2026-10-03T00:00:00Z"
}

Firmar una transacción

POST
/web3/transaction/{wallet_id}/signRaw

Firma insegura

No se recomienda la firma raw. Una solicitud maliciosa puede engañarte para que firmes una transacción que roba fondos. Firma solo payloads que hayas verificado.

Envía una transacción para su firma y procesamiento. Devuelve un transaction_id.

  • EVM: from, to, nonce, gasLimit, data, value, chainId, maxFeePerGas, maxPriorityFeePerGas y accessList.
  • Solana: data (transacción serializada en base64), from, meta.tx_method (solana_signTransaction) y chainId ("1399811149").

El signTransaction del SDK para EVM devuelve un hash de transacción. sendTransaction completa los campos de la transacción y devuelve una respuesta de transacción.

Request

POST
/web3/transaction/:wallet_id/signRaw
import { EtherSigner, Environment } from '@fystack/sdk'
import { JsonRpcProvider, parseEther } from 'ethers'

const provider = new JsonRpcProvider(process.env.RPC_URL!)
const signer = new EtherSigner(
  {
    apiKey: process.env.API_KEY!,
    apiSecret: process.env.API_SECRET!,
  },
  Environment.Production,
  provider,
)

signer.setWallet('YOUR_WALLET_ID')
const tx = await signer.sendTransaction({
  to: '0x7c2BbE2e02af09F1cf9aFd4A79EC201DC841675a',
  value: parseEther('0.01'),
})

console.log(tx.hash)

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87"
}

Obtener el estado de la transacción

GET
/web3/transaction/{wallet_id}/{transaction_id}

Devuelve transaction_id, status, method, approvals, created_at y updated_at, con hash y failed_reason cuando están disponibles.

Los signers de transacciones del SDK esperan confirmed o completed con un hash, y se detienen ante failed o rejected.

Request

GET
/web3/transaction/:wallet_id/:transaction_id
import { APIService, Environment } from '@fystack/sdk'

const api = new APIService(
  { apiKey: process.env.API_KEY!, apiSecret: process.env.API_SECRET! },
  Environment.Production,
)

const status = await api.getTransactionStatus('YOUR_WALLET_ID', 'TRANSACTION_ID')
console.log(status.hash)

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87",
  "status": "pending",
  "method": "solana_signTransaction",
  "approvals": [],
  "created_at": "2026-10-03T00:00:00Z",
  "updated_at": "2026-10-03T00:00:00Z"
}