Skip to main content
POST
/
api
/
grid
/
v1
/
accounts
/
{address}
/
submit
cURL
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/accounts/{address}/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-grid-environment: <x-grid-environment>' \
  --data '
{
  "kms_payloads": [
    [
      {
        "provider": "privy",
        "kms_signed_payload": "<unknown>",
        "signature": "<string>"
      }
    ]
  ],
  "transactions": [
    "<string>"
  ]
}
'
{
  "data": {
    "results": [
      {
        "confirmed_at": "2023-11-07T05:31:56Z",
        "index": 1,
        "transaction_signature": "<string>"
      }
    ],
    "partial_failure": "<unknown>"
  },
  "metadata": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
This endpoint submits a previously prepared transaction to the blockchain after verifying the required signatures from Grid Account authorization keys.
Using the Grid API directly requires advanced configurations. Grid SDK is the recommended way to submit transactions. It handles transaction preparation, signing, automatic failover, and submission. Learn more about the Grid SDK in the Grid SDK guide.
This endpoint requires a prepared transaction and valid signatures. Use transaction preparation endpoints first, then sign the KMS payload with your decrypted authorization key before calling this endpoint.

​
Account Type Signing Flows

Grid supports two types of accounts with different signing requirements. Choose the appropriate flow based on how your account was created:
For accounts created with email authentication (using Privy):

​
High-Level Process

  1. Prepare Transaction: Call transaction preparation endpoints (payments, transfers, etc.)
  2. Receive KMS Payload: Extract the kms_payload from the preparation response
  3. Sign Payload: Use your decrypted Privy authorization key to sign the canonical JSON
  4. Submit Transaction: Call this endpoint with the signature and transaction data

​
Key Requirements

  • Authorization keys from email account creation/authentication
  • JSON canonicalization of the KMS payload (recursive key sorting)
  • ECDSA P-256 SHA-256 signature algorithm

​
Complete Implementation Guide

For detailed implementation including HPKE keypair generation, authorization key decryption, JSON canonicalization, payload signing, and language-agnostic examples, see the Primary Provider Integration guide.
For accounts created with Ed25519 public keys:

​
Signing Process

  1. Prepare Transaction: Call transaction preparation endpoints (payments, transfers, etc.)
  2. Receive Transaction: Extract the prepared Solana transaction from the response
  3. Sign Transaction: Use your Ed25519 private keys with standard Solana transaction signing (e.g., web3.js)
  4. Submit Transaction: Call this endpoint with the signed transaction

​
Signature Requirements

  • Ed25519 private keys corresponding to the public keys specified during account creation
  • Threshold signatures meeting the account’s signing threshold
  • Standard Solana transaction signing (no KMS payload or JSON canonicalization required)
Signer-based accounts use regular Solana transaction signing with libraries like web3.js. No KMS payload processing or JSON canonicalization is required.
The signed transaction proves you have access to the required number of Grid Account signing keys and authorizes the transaction execution.

​
Implementation with web3.js

import { Transaction } from '@solana/web3.js';
import { Keypair } from '@solana/web3.js';

// Extract prepared transaction from API response
const preparedTransaction = Transaction.from(
  Buffer.from(response.transaction, 'base64')
);

// Sign with your Ed25519 keypairs (threshold signatures required)
const signers = [keypair1, keypair2]; // Your Ed25519 keypairs
preparedTransaction.sign(...signers);

// Submit the signed transaction
const signedTransaction = preparedTransaction.serialize();

​
KMS Payload Schema

The kms_payloads field contains the signed KMS payloads from your key management provider. Each payload has a provider and a kms_signed_payload whose shape depends on the provider. See the auto-generated request body schema below for full field details.
Turnkey accounts must use kms_signed_payload. The top-level signature field is only supported for Privy as a legacy fallback.

​
Request Examples

{
  "transaction": "<base64_encoded_transaction>",
  "kms_payloads": [
    {
      "provider": "privy",
      "kms_signed_payload": {
        "signature": "<base64_der_ecdsa_signature>"
      }
    }
  ]
}

{
  "transaction": "<base64_encoded_transaction>",
  "kms_payloads": [
    {
      "provider": "turnkey",
      "kms_signed_payload": {
        "public_key": "<hex_p256_public_key>",
        "signature": "<hex_signature>",
        "timestamp_ms": "<unix_timestamp_ms>"
      }
    }
  ]
}
When submitting multiple transactions, use transactions (plural) and nest kms_payloads as an array of arrays — one inner array per transaction:
{
  "transactions": ["<base64_tx_1>", "<base64_tx_2>"],
  "kms_payloads": [
    [
      {
        "provider": "privy",
        "kms_signed_payload": {
          "signature": "<signature_for_tx_1>"
        }
      }
    ],
    [
      {
        "provider": "privy",
        "kms_signed_payload": {
          "signature": "<signature_for_tx_2>"
        }
      }
    ]
  ]
}
This format places the signature at the top level instead of inside kms_signed_payload. It is supported for backward compatibility with Privy accounts only.
{
  "transaction": "<base64_encoded_transaction>",
  "kms_payloads": [
    {
      "provider": "privy",
      "signature": "<base64_der_ecdsa_signature>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Headers

​
x-grid-environment
string
required

Solana network environment (sandbox, devnet, mainnet)

Path Parameters

​
address
string
required

Smart account address (Solana public key)

Body

application/json

Multiple transactions format (new)

​
kms_payloads
object[][]
required
​
transactions
string[]
required

Response

Transaction submitted successfully

​
data
object
required

Response payload - supports both legacy single-transaction and new multi-transaction formats

​
metadata
object
required