Grid implements idempotency to ensure that operations can be safely retried without creating duplicate resources or processing the same request multiple times.

​
How it works

When you make a request to Grid’s API, you can include an x-idempotency-key header. If you retry a failed request with the same key, Grid ensures that the operation is only processed once.

​
Using idempotency keys

Include an x-idempotency-key header in your request:

curl https://api.squads.xyz/grid/smart-accounts \
  -H "x-idempotency-key: payment_123_xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "policies": {
      "authorities": [
        {
          "address": "0x123...",
          "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
        }
      ],
      "threshold": 1
    },
    "grid_customer_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

​
Key requirements

  • The x-idempotency-key header is optional but recommended for POST requests
  • Keys must be unique for each operation
  • Keys are case-sensitive
  • Keys can contain letters, numbers, hyphens, and underscores

​
Validity periods

Most idempotency keys are valid for 24 hours. However, intent creation idempotency keys are only valid for 2 minutes. After this period, you must generate a new key for subsequent intent creation requests.

​
Successful response (new request)

{
  "data": {
    "smart_account_address": "0x123...",
    "grid_user_id": "123e4567-e89b-12d3-a456-426614174000",
    "policies": {
      "authorities": [
        {
          "address": "0x123...",
          "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
        }
      ],
      "threshold": 1
    },
    "created_at": "2024-03-20T12:00:00Z"
  }
}

​
Error response (invalid key)

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "timestamp": "2024-03-20T12:00:00Z",
    "details": [
      {
        "field": "x-idempotency-key",
        "code": "INVALID_IDEMPOTENCY_KEY",
        "message": "The provided idempotency key is invalid"
      }
    ]
  }
}