> ## Documentation Index
> Fetch the complete documentation index at: https://developers.squads.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Grid in minutes

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](https://squads-grid.typeform.com/contact?typeform-source=squads.xyz) to get one.

## Authentication

All Grid API requests require two headers:

<ParamField header="x-grid-environment" type="string" required>
  The environment you're using. Can be `sandbox` or `production`.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token authentication header. Format: `Bearer YOUR_API_KEY`
</ParamField>

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "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"
  }
}
```

<Tip>
  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.
</Tip>

### 2. Request KYC Verification

To enable banking features, request a KYC verification link:

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

<Note>
  In `sandbox` mode, the `tos_status` will always be `pending`.
</Note>

```json theme={null}
{
    "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:

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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"
      }
    }
  }'
```

<Tip>
  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.
</Tip>

The response includes payment intent details:

```json theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

<Tip>
  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.
</Tip>

The response includes the confirmed transfer details:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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