POST /api/v1/user-operations

Parameters

Name	Location	Details
`X-Juicebox-Account`	header / required	Enrolled account identity, including authority chain and lowercase owner address. Enrollment derives this identity before the account exists.
`X-Juicebox-Signer`	header / required	Owner wallet or authorized bot address that signed this request.
`X-Juicebox-Issued-At`	header / required	Unix seconds, sent as 1–13 decimal digits without leading zeros; at most 30 seconds ahead of server time.
`X-Juicebox-Expires-At`	header / required	Unix seconds, sent as 1–13 decimal digits without leading zeros; in the future and within 300 seconds of issuedAt.
`X-Juicebox-Nonce`	header / required	Fresh random 32-byte lowercase nonce. A consumed nonce cannot be retried.
`X-Juicebox-Signature`	header / required	EIP-712 CenterRequest signature over every signed field. Contract-owner signatures may vary in length. This is a computed request proof, not a reusable API key.
`X-Juicebox-Grant`	header / optional	Authorized bot grant ID. Required for a bot; omit for the owner, signing grantId as the empty string.
`Idempotency-Key`	header / required	Signed retry identity. Required on plan creation and transaction submission. Preserve exact method, target, Content-Type, and body bytes; use a fresh request nonce and signature.

Request body

Option 1

Field	Type	Details
`planId`	string (uuid) required
`stepIndexes`	array required
`sessionId`	string (uuid) optional
`sponsorAuthorization`	string optional	Short-lived server-issued application sponsorship voucher bound to this principal and idempotency key, and to the plan by id and steps or by its exact calls and manifest. Not accepted with sessionId.

Option 2

Field Type Details

plan

object
required

A smart-account plan created here, idempotent on its own key, exactly as POST /smart-accounts/bindings/{id}/plans would.

Fields

Field	Type	Details
`bindingId`	string required
`operation`	string required
`input`	value required
`idempotencyKey`	string required

sponsorAuthorization string
required A voucher bound to the plan's exact calls and manifest.

JSON schema

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "planId": {
          "$ref": "#/components/schemas/ResourceId"
        },
        "stepIndexes": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 31
          },
          "minItems": 1,
          "maxItems": 16,
          "uniqueItems": true
        },
        "sessionId": {
          "$ref": "#/components/schemas/ResourceId"
        },
        "sponsorAuthorization": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096,
          "description": "Short-lived server-issued application sponsorship voucher bound to this principal and idempotency key, and to the plan by id and steps or by its exact calls and manifest. Not accepted with sessionId."
        }
      },
      "required": [
        "planId",
        "stepIndexes"
      ],
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "required": [
              "sessionId"
            ]
          },
          "then": {
            "properties": {
              "stepIndexes": {
                "maxItems": 1
              }
            }
          }
        }
      ],
      "description": "Use the creating principal of a durable smart-account plan. Indices must increase in original order. Omit `sessionId` for current Safe-owner threshold signing; a bound bot supplies `sessionId` for one approved action."
    },
    {
      "type": "object",
      "properties": {
        "plan": {
          "type": "object",
          "properties": {
            "bindingId": {
              "$ref": "#/components/schemas/Hash"
            },
            "operation": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "input": {},
            "idempotencyKey": {
              "type": "string",
              "pattern": "^[A-Za-z0-9:_-]{1,128}$"
            }
          },
          "required": [
            "bindingId",
            "operation",
            "input",
            "idempotencyKey"
          ],
          "additionalProperties": false,
          "description": "A smart-account plan created here, idempotent on its own key, exactly as POST /smart-accounts/bindings/{id}/plans would."
        },
        "sponsorAuthorization": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096,
          "description": "A voucher bound to the plan's exact calls and manifest."
        }
      },
      "required": [
        "plan",
        "sponsorAuthorization"
      ],
      "additionalProperties": false,
      "description": "One call for a sponsored payment: the plan and the operation over every one of its steps. When the voucher does not cover the plan built, the answer carries the plan alone with `sponsorship: refused`."
    }
  ]
}

Response 201

Option 1

Field Type Details

id string (uuid)
required

planId string (uuid)
required

planCommitment string
required

stepIndexes array
required

chainId integer
required

entryPoint string
required

operation

object
required

Unpacked EntryPoint v0.7 operation. RPC integers are hexadecimal quantities; reviewed policy amounts use decimal strings. No v0.8 or EIP-7702 extensions.

Fields

Field	Type	Details
`sender`	string required
`nonce`	string required	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`factory`	string optional
`factoryData`	string optional
`callData`	string required
`callGasLimit`	string required	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`verificationGasLimit`	string required	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`preVerificationGas`	string required	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`maxFeePerGas`	string required	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`maxPriorityFeePerGas`	string required	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`paymaster`	string optional
`paymasterVerificationGasLimit`	string optional	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`paymasterPostOpGasLimit`	string optional	Canonical lowercase hexadecimal RPC quantity, with no leading zeros.
`paymasterData`	string optional
`signature`	string required	Public preparations and reads always omit submitted account signature bytes. Values: `["0x"]`

operationHash string
required

commitment string
required

accountBindingId string
required

accountStateHash string
required

session

object
optional

Fields

Field	Type	Details
`id`	string (uuid) required
`policyHash`	string required
`compiledHash`	string required
`generation`	value required	Positive uint256 as an exact decimal string.
`grantId`	string (uuid) required
`permissionId`	string required
`sessionKey`	string required
`observationHash`	string required

gasPolicyId string
required

providerId string
required

createdAt integer
required Unix timestamp in milliseconds.

expiresAt integer
required Unix timestamp in milliseconds.

revision integer
required

state

string
required

Values: ["prepared","submitting","submission_unknown","pending","unknown","confirming","confirmed","reverted","expired"]

signing one of
required

submission

object
optional

Fields

Field	Type	Details
`commitment`	string required
`startedAt`	integer required	Unix timestamp in milliseconds.

observation

object
optional

Fields

Field	Type	Details
`state`	string required	Values: `["pending","unknown","confirming","confirmed","reverted","expired"]`
`operationHash`	string required
`transactionHash`	string optional
`receipt`	object optional
`scopedLogs`	array optional
`semantic`	object optional
`reason`	string optional

Option 2

Field Type Details

plan

object
required

Fields

Field	Type	Details
`id`	string (uuid) required
`account`	string required
`operation`	string required
`draft`	object required
`commitment`	string required
`createdAt`	integer required	Unix timestamp in milliseconds.
`expiresAt`	integer required	Unix timestamp in milliseconds.
`revision`	integer required
`smartAccount`	object optional
`status`	string required	Values: `["prepared","pending","partial","blocked","reorged","expired","transactions_confirmed"]`
`steps`	array required
`confirmationScope`	string required

operation

object
optional

Fields

Field	Type	Details
`id`	string (uuid) required
`planId`	string (uuid) required
`planCommitment`	string required
`stepIndexes`	array required
`chainId`	integer required
`entryPoint`	string required
`operation`	object required	Unpacked EntryPoint v0.7 operation. RPC integers are hexadecimal quantities; reviewed policy amounts use decimal strings. No v0.8 or EIP-7702 extensions.
`operationHash`	string required
`commitment`	string required
`accountBindingId`	string required
`accountStateHash`	string required
`session`	object optional
`gasPolicyId`	string required
`providerId`	string required
`createdAt`	integer required	Unix timestamp in milliseconds.
`expiresAt`	integer required	Unix timestamp in milliseconds.
`revision`	integer required
`state`	string required	Values: `["prepared","submitting","submission_unknown","pending","unknown","confirming","confirmed","reverted","expired"]`
`signing`	one of required
`submission`	object optional
`observation`	object optional

sponsorship

string
required

Values: ["accepted","refused"]

JSON schema

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/UserOperation"
    },
    {
      "$ref": "#/components/schemas/SponsoredPaymentPreparation"
    }
  ]
}