Skip to main content
POST
/
accounts:custom
cURL
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/accounts:custom \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-grid-environment: <x-grid-environment>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "policies": {
    "signers": [
      {
        "address": "<string>",
        "permissions": [
          "CAN_INITIATE"
        ],
        "role": "primary",
        "provider": "privy"
      }
    ],
    "threshold": 1,
    "admin_address": "<string>",
    "time_lock": 1
  },
  "memo": "<string>"
}
'
{
  "data": {
    "address": "<string>",
    "policies": {
      "signers": [
        {
          "address": "<string>",
          "permissions": [
            "CAN_INITIATE"
          ]
        }
      ],
      "threshold": 1,
      "adminAddress": "<string>",
      "timeLock": 1
    },
    "type": "<string>"
  },
  "metadata": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
Creates a new Grid smart account with a custom configuration of signers. This endpoint supports two types of signers:
  • Email signers: MPC-managed wallets created via Turnkey or Privy
  • Pubkey signers: External public keys you manage yourself
This provides flexibility for multi-signature setups, backup signers, and custom permission configurations.

​
Endpoint

POST /accounts:custom

​
Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token
x-grid-environmentstringYesTarget environment: sandbox or production
x-idempotency-keystringNoPrevents duplicate account creation on retries

​
Request Body

{
  "policies": {
    "threshold": 2,
    "signers": [
      {
        "type": "email",
        "email": "alice@example.com",
        "provider": "turnkey",
        "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "type": "email",
        "email": "bob@example.com",
        "provider": "privy",
        "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "type": "pubkey",
        "address": "7xK...abc",
        "permissions": ["CAN_VOTE"]
      }
    ],
    "timeLock": 0,
    "adminAddress": null
  },
  "memo": "Optional memo for the transaction"
}

​
Request Fields

FieldTypeRequiredDescription
policiesobjectYesAccount policy configuration
policies.thresholdnumberYesNumber of signatures required (1-10)
policies.signersarrayYesArray of signer configurations (1-10 signers)
policies.timeLocknumberNoTime lock in seconds before transactions can execute
policies.adminAddressstringNoAdmin address that can modify account settings
memostringNoOptional memo included in the creation transaction

​
Signer Types

​
Email Signer

Creates an MPC-managed wallet for the specified email address. 
{
  "type": "email",
  "email": "user@example.com",
  "provider": "turnkey",
  "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
}
FieldTypeDescription
typestringMust be "email"
emailstringEmail address for the signer
providerstringMPC provider: "turnkey" or "privy"
permissionsarrayList of permissions for this signer

​
Pubkey Signer

Uses an existing Solana public key that you manage externally. 
{
  "type": "pubkey",
  "address": "7xK...abc",
  "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
}
FieldTypeDescription
typestringMust be "pubkey"
addressstringSolana public key (base58)
permissionsarrayList of permissions for this signer

​
Signer Permissions

PermissionDescription
CAN_INITIATECan create new transaction proposals
CAN_VOTECan approve or reject proposals
CAN_EXECUTECan execute approved transactions
At least one signer must have each permission type. The threshold cannot exceed the number of signers with CAN_VOTE permission.

​
Response

{
  "type": "signers",
  "address": "5nP...xyz",
  "policies": {
    "threshold": 2,
    "signers": [
      {
        "address": "3ci...abc",
        "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "address": "8kL...def",
        "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "address": "7xK...abc",
        "permissions": ["CAN_VOTE"]
      }
    ],
    "timeLock": 0,
    "adminAddress": null
  }
}

​
Response Fields

FieldTypeDescription
typestringAlways "signers" for this endpoint
addressstringThe created smart account address
policies.thresholdnumberRequired number of signatures
policies.signersarrayResolved signers with their on-chain addresses
policies.timeLocknumberTime lock value (if set)
policies.adminAddressstringAdmin address (if set)

​
Implementation Flow

1

Define Signer Configuration

Determine the signers for your account: email-based MPC wallets, external pubkeys, or a combination
2

Set Threshold

Choose how many signatures are required to execute transactions
3

Create Account

Call this endpoint with your configuration
4

Store Addresses

Save the returned smart account address and resolved signer addresses for future use

​
Use Cases

​
Multi-Signature Treasury

{
  "policies": {
    "threshold": 2,
    "signers": [
      {
        "type": "email",
        "email": "cfo@company.com",
        "provider": "turnkey",
        "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "type": "email",
        "email": "ceo@company.com",
        "provider": "turnkey",
        "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "type": "email",
        "email": "backup@company.com",
        "provider": "privy",
        "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
      }
    ]
  }
}

​
User Account with Backup

{
  "policies": {
    "threshold": 1,
    "signers": [
      {
        "type": "email",
        "email": "user@example.com",
        "provider": "turnkey",
        "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
      },
      {
        "type": "email",
        "email": "user@example.com",
        "provider": "privy",
        "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
      }
    ]
  }
}
The same email can be used with different MPC providers to create redundant backup signers.

​
Important Notes

  • The account is created on-chain immediately and returns the resolved signer addresses
  • Email signers have MPC wallets created automatically by the specified provider
  • Idempotency keys prevent duplicate accounts when retrying failed requests
  • Response only includes resolved addresses, not emails or MPC provider metadata

​
Error Handling

Common errors:
ErrorDescription
InvalidSignerConfigurationMissing required permissions or threshold exceeds voters
DuplicateEmailProviderSame email used twice with the same MPC provider
DuplicateAddressMultiple signers resolve to the same address
InvalidPubkeyInvalid Solana public key format
InvalidMPCProviderUnsupported MPC provider specified

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Headers

​
x-grid-environment
string
required

Solana network environment (sandbox, production)

​
x-idempotency-key
string
required

Optional idempotency key to prevent duplicate account creation

Body

application/json
​
policies
object
required
​
memo
string | null

Response

Smart account created successfully

​
data
object
required
​
metadata
object
required