Skip to main content
POST
/
api
/
grid
/
v1
/
accounts
/
{address}
/
proposals
cURL
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/accounts/{address}/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-grid-environment: <x-grid-environment>' \
  --data '
{
  "signer": "<string>",
  "transaction": "<string>",
  "type": "custom",
  "fee_config": {
    "currency": "sol",
    "payer_address": "<string>",
    "self_managed_fees": true
  }
}
'
{
  "data": {
    "proposalAddress": "<string>",
    "signer": "<string>",
    "transactions": [
      "<string>"
    ]
  },
  "metadata": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
Creates a proposal that requires consensus from multiple signers before execution. Proposals enable coordinated multi-party approval for transactions and account settings changes.
Proposals are an enterprise-tier feature. Free and Pro tier accounts will receive a 403 Forbidden error.

​
Proposal Types

​
Custom Proposals

Execute arbitrary Solana transactions through your smart account: 
const response = await grid.createProposal(accountAddress, {
    type: "custom",
    transaction: serializedVersionedTransaction,
    signer: creatorPublicKey,
});

​
Settings Proposals

Modify account configuration with up to 10 actions per proposal: 
const response = await grid.createProposal(accountAddress, {
    type: "settings",
    actions: [
        { type: "AddSigner", newSigner: { address: newKey, mask: 7 } },
        { type: "ChangeThreshold", newThreshold: 2 },
    ],
    signer: creatorPublicKey,
});
Available actions: AddSigner, RemoveSigner, ChangeThreshold, SetTimeLock, AddSpendingLimit, RemoveSpendingLimit, SetArchivalAuthority

​
Transfer Proposals

Transfer tokens or SOL from your smart account through a proposal: 
const response = await grid.createProposal(accountAddress, {
    type: "transfer",
    token: "usdc",
    destination: recipientPublicKey,
    rawAmount: 1000000,
    signer: creatorPublicKey,
});
Supported tokens: sol, usdc, usdt, pyusd, eurc, or a custom mint
ParameterTypeRequiredDescription
tokenstring | objectYesStandard token name or custom mint object
destinationstringYesRecipient’s Solana address
rawAmountnumberYesAmount in the token’s smallest unit (e.g. lamports for SOL, 10^6 for USDC)
mintDecimalsnumberNoOverride decimal precision; validated against on-chain mint data
signerstringYesPublic key of the proposal creator

​
Permission Requirements

The signer must have CAN_INITIATE permission (mask includes value 1). The signer address cannot be the smart account address itself.

​
Transaction Splitting

Solana transactions have a 1232-byte limit. If your proposal exceeds this, the API returns multiple transactions that must be signed and submitted in order.

​
Fee Configuration

By default, the Grid paymaster sponsors fees. Enterprise accounts can specify custom fee handling: 
{
  fee_config: {
    currency: "SOL",
    payer_address: payerPublicKey,
    self_managed_fees: true  // Skip simulation
  }
}

​
Implementation Flow

1

Prepare Proposal

Build your transaction or define settings actions.
2

Create Proposal

Call this endpoint. Returns unsigned transaction(s) and the proposal address.
3

Sign and Submit

Sign all returned transactions and submit to Solana in order.
The proposal is now Active and awaiting votes.

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Headers

​
x-grid-environment
string
required

Target Solana environment

Path Parameters

​
address
string
required

Smart account address (Solana public key)

Body

application/json
​
signer
string
required
​
transaction
string
required
​
type
enum<string>
required
Available options:
custom
​
fee_config
object

Response

Proposal Create transaction(s) created successfully

​
data
object
required
​
metadata
object
required