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

​
Prerequisites

​
Authentication

All Grid API requests require two headers:

​
x-grid-environment
string
required

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

​
Authorization
string
required

Bearer token authentication header. Format: Bearer YOUR_API_KEY

​
Basic Flow

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

  1. Create a smart account
  2. Request KYC verification (for fiat features)
  3. Create virtual accounts (for fiat features)
  4. 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