Quickstart

You’ll learn how to set up your environment, make your first API call, and understand the basic concepts.

Prerequisites

A Grid API key. Fill out the signup form to get one.

Authentication

All Grid API requests require two headers:

string

required

The environment you’re using. Can be sandbox or production.

string

required

Bearer token authentication header. Format: Bearer YOUR_API_KEY

Basic Flow

Here’s a typical flow for using the Grid API:

Create a smart account
Request KYC verification (for fiat features)
Create virtual accounts (for fiat features)
Create and manage payment intents

1. Create a Smart Account

First, create a smart account with specific policies and authorities:

curl -X POST https://grid.squads.xyz/api/v0/grid/smart-accounts \
  -H "x-grid-environment: sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policies": {
      "authorities": [
        {
          "address": "0x...",
          "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
        }
      ],
      "threshold": 1
    }
  }'

The response will include your smart account details:

{
  "data": {
    "smart_account_address": "0x...",
    "grid_user_id": "uuid",
    "policies": {
      "authorities": [
        {
          "address": "0x...",
          "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
        }
      ],
      "admin_address": null,
      "threshold": 1,
      "time_lock": null
    },
    "created_at": "2025-05-28T19:20:28.425823409Z"
  },
  "metadata": {
    "timestamp": "2025-05-28T19:20:28.425823819Z"
  }
}

Make sure to save the grid_user_id from the response. This is the main identifier for your smart account and will be required for subsequent API calls.

2. Request KYC Verification

To enable banking features, request a KYC verification link:

The X-Idempotency-Key header is required on this endpoint, to prevent multiple kyc processes from being initiated.

curl -X POST https://grid.squads.xyz/api/v0/grid/smart-accounts/{smart_account_address}/kyc \
  -H "x-grid-environment: sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Idempotency-Key: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "grid_user_id": "uuid",
    "type": "individual",
    "email": "user@example.com",
    "full_name": "John Doe",
    "endorsements": ["endorsement1", "endorsement2"]
  }'

The response includes a KYC verification as well as a Terms of Service URL:

{
  "data": {
    "id": "uuid",
    "customer_id": "uuid",
    "kyc_link": "https://kyc-verification-url",
    "created_at": "2024-03-20T12:00:00Z"
  },
  "metadata": {
    "timestamp": "2024-03-20T12:00:00Z",
    "request_id": "req_123456789"
  }
}

3. Check KYC Status

You can check the status of a KYC verification by calling the GET endpoint:

curl -X GET https://grid.squads.xyz/api/v0/grid/smart-accounts/{smart_account_address}/kyc/{kyc_id} \
  -H "x-grid-environment: sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Idempotency-Key: <uuid>" \

The response includes the status of the KYC verification:

In sandbox mode, the tos_status will always be pending.

{
    "data": {
        "id": "uuid",
        "type": "individual",
        "status": "approved",
        "tos_status": "pending",
        "rejection_reasons": [],
        "requirements_due": [
            "external_account"
        ],
        "created_at": "2025-05-28T19:37:10.123+00:00",
        "updated_at": "2025-05-28T19:37:10.123+00:00"
    },
    "metadata": {
        "timestamp": "2025-05-28T19:52:33.846638786Z"
    }
}

4. Create Virtual Accounts

Create virtual accounts for different currencies:

The X-Idempotency-Key header is required on this endpoint, to prevent unnecessary virtual accounts from being created.

curl -X POST https://grid.squads.xyz/api/v0/grid/smart-accounts/{smart_account_address}/virtual-accounts \
  -H "x-grid-environment: sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Idempotency-Key: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "grid_user_id": "uuid",
    "currency": "usd"
  }'

The response includes bank account details:

{
  "data": {
    "id": "9958f3dd-c974-4491-9e34-99ba510d77e6",
    "customer_id": "7f05d965-1c30-4607-b7de-7b89a1de19bd",
    "source_deposit_instructions": {
      "currency": "usd",
      "bank_beneficiary_name": "John Doe",
      "bank_name": "Bank of Nowhere",
      "bank_address": "1800 North Pole St., Orlando, FL 32801",
      "bank_routing_number": "101019644",
      "bank_account_number": "900956625572",
      "payment_rails": ["ach_push", "wire"]
    },
    "destination": {
      "currency": "usdc",
      "payment_rail": "solana",
      "address": "3zWyEvA2GGVwnmA8yCQppJYj14f1scPRoxguhWjhbmsM"
    },
    "status": "activated",
    "developer_fee_percent": "0.0"
  },
  "metadata": {
    "timestamp": "2025-05-28T20:18:50.842883132Z"
  }
}

5. Create and Manage Payment Intents

Create a payment intent to transfer funds:

curl -X POST https://grid.squads.xyz/api/v0/grid/smart-accounts/{smart_account_address}/payment-intents \
  -H "x-grid-environment: sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1000000",
    "grid_user_id": "uuid",
    "source": {
      "payment_rail": "solana",
      "currency": "usdc",
      "smart_account_address": "0x..."
    },
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "details": {
        "account_owner_name": "John Doe",
        "address": {
          "street_line_1": "123 Main St",
          "city": "New York",
          "state": "NY",
          "country": "US"
        },
        "account_type": "us",
        "idempotency_key": "unique-key-123",
        "account": {
          "checking_or_savings": "checking",
          "routing_number": "987654321",
          "last_4": "6789"
        },
        "bank_name": "Example Bank"
      }
    }
  }'

If you’ve previously sent funds to a bank account, you can reuse the external account ID instead of providing all the bank details again.

The response includes payment intent details:

{
  "data": {
    "id": "payment-intent-id",
    "payment_rail": "ach",
    "amount": "1000000",
    "currency": "usd",
    "source": {
      "type": "SMART_ACCOUNT",
      "address": "0x..."
    },
    "destination": {
      "type": "NEW_EXTERNAL_ACCOUNT",
      "details": {
        "account_type": "checking",
        "account_name": "My Account",
        "account_holder_name": "John Doe",
        "account_holder_type": "individual",
        "routing_number": "987654321",
        "account_number": "123456789",
        "bank_name": "Example Bank"
      }
    },
    "status": "awaiting_funds",
    "created_at": "2024-03-20T12:00:00Z",
    "updated_at": "2024-03-20T12:00:00Z",
    "authorities": ["0x...", "0x..."],
    "threshold": 2,
    "intent_payload": "base64-encoded-payload",
    "mpc_payload": "base64-encoded-mpc-payload"
  },
  "metadata": {
    "timestamp": "2024-03-20T12:00:00Z",
    "request_id": "req_123456789"
  }
}

6. Confirm Payment Intent

Once you have the payment intent, authorize it with the required authorities:

curl -X POST https://grid.squads.xyz/api/v0/grid/smart-accounts/{smart_account_address}/payment-intents/{payment_intent_id}/confirm \
  -H "x-grid-environment: sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_payload": "base64-encoded-authorized-payload",
    "mpc_payload": "base64-encoded-authorized-mpc-payload"
  }'

When using MPC (Multi-Party Computation) for authorization, you’ll need to provide both the intent_payload and mpc_payload. The mpc_payload contains the authorization from the MPC provider.

The response includes the confirmed transfer details:

{
  "data": {
    "Bridge": {
      "id": "transfer-id",
      "state": "payment_submitted",
      "on_behalf_of": "0x...",
      "amount": "1000000",
      "developer_fee": "100.00",
      "source": {
        "payment_rail": "solana",
        "currency": "usdc"
      },
      "destination": {
        "payment_rail": "ach",
        "currency": "usd"
      },
      "receipt": {
        "initial_amount": "1000000",
        "developer_fee": "100.00",
        "exchange_fee": "100.00",
        "subtotal_amount": "1000000",
        "remaining_prefunded_balance": "1000000",
        "gas_fee": "100.00",
        "final_amount": "1000000",
        "exchange_rate": "1.00"
      },
      "created_at": "2024-03-20T12:00:00Z",
      "updated_at": "2024-03-20T12:00:00Z"
    }
  },
  "metadata": {
    "timestamp": "2024-03-20T12:00:00Z",
    "request_id": "req_123456789"
  }
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "code": "ERROR_CODE",
  "message": "Human readable error message",
  "details": {
    "field": "field_name",
    "code": "FIELD_ERROR_CODE",
    "message": "Field-specific error message"
  }
}

Supported Currencies

Grid currently supports the following currencies:

USD (US Dollar)
EUR (Euro)
MXN (Mexican Peso)
USDC (USD Coin)
USDT (Tether)
USDB (USD Base)
DAI (Dai Stablecoin)
PYUSD (PayPal USD)
EURC (Euro Coin)

Supported Payment Rails

Grid supports the following payment rails:

ACH
ACH Push
ACH Same Day
SEPA
SWIFT
Wire
Arbitrum
Avalanche C-Chain
Base
Bridge Wallet
Ethereum
Optimism
Polygon
Solana
Stellar
Tron

Get Started

Core Concepts

Modules

Prerequisites

Authentication

Basic Flow

1. Create a Smart Account

2. Request KYC Verification

3. Check KYC Status

4. Create Virtual Accounts

5. Create and Manage Payment Intents

6. Confirm Payment Intent

Error Handling

Supported Currencies

Supported Payment Rails

​Prerequisites

​Authentication

​Basic Flow

​1. Create a Smart Account

​2. Request KYC Verification

​3. Check KYC Status

​4. Create Virtual Accounts

​5. Create and Manage Payment Intents

​6. Confirm Payment Intent

​Error Handling

​Supported Currencies

​Supported Payment Rails

Prerequisites

Authentication

Basic Flow

1. Create a Smart Account

2. Request KYC Verification

3. Check KYC Status

4. Create Virtual Accounts

5. Create and Manage Payment Intents

6. Confirm Payment Intent

Error Handling

Supported Currencies

Supported Payment Rails