POST /api/v1/operations/prepare_721_pay/plans

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

Field Type Details

project

object
required

Fields

Field Type Details

chainId one of
required

projectId string
required

version

number
optional

Values: [6]

Default: 6

account string
required

token string
required Token address; native ETH is 0x000000000000000000000000000000000000EEEe.

amount string
required Fresh payment amount in the token’s smallest units. Use 0 for free tiers or eligible NFT-credit purchases.

beneficiary string
required

tierIds array
required

slippageBps

integer
optional

Slippage in basis points, 0–4950. Default 100. Raise it only within what the payer accepts, such as a payFailure's retrySlippageBps.

Default: 100

minReturnedTokens string
optional Explicit minimum fungible project tokens for the beneficiary, in 18-decimal base units, replacing the quoted count less slippageBps. Needed when the quote warns that the default minimum sits above the simulated fill (a buyback hook beside the NFT hook). NFT delivery is checked either way.

allowOverspending

boolean
optional

Default: false

skipSplits boolean
optional Buyback 1.4 only. Unset means on wherever the project's buyback hook is 1.4 and no metadata is given, as the apps pay: the hook buys from the pool when that beats the payer's share of a mint, and the tokens it buys go to the beneficiary without the reserved split (they already exist, so nothing is issued for them and the split gets none). Minting still pays the split. The default minimum is then the SDK's (prepareUserPay): with a pool quote, the beneficiary's part of the floored quote, which the hook also enforces. Pass false when the payment should honor the project's splits, such as routing fees or revenue into a project. Where it cannot apply (no buyback hook, hook 1.0 or 1.1.1, the caller's own metadata) unset means off, and an explicit true is refused. The quote's skipSplits says which applied and why.

JSON schema

{
  "type": "object",
  "properties": {
    "project": {
      "type": "object",
      "properties": {
        "chainId": {
          "anyOf": [
            {
              "type": "number",
              "const": 1
            },
            {
              "type": "number",
              "const": 10
            },
            {
              "type": "number",
              "const": 8453
            },
            {
              "type": "number",
              "const": 42161
            },
            {
              "type": "number",
              "const": 11155111
            },
            {
              "type": "number",
              "const": 11155420
            },
            {
              "type": "number",
              "const": 84532
            },
            {
              "type": "number",
              "const": 421614
            }
          ]
        },
        "projectId": {
          "type": "string",
          "maxLength": 78,
          "pattern": "^(0|[1-9][0-9]*)$"
        },
        "version": {
          "default": 6,
          "type": "number",
          "const": 6
        }
      },
      "required": [
        "chainId",
        "projectId"
      ],
      "additionalProperties": false
    },
    "account": {
      "type": "string"
    },
    "token": {
      "description": "Token address; native ETH is 0x000000000000000000000000000000000000EEEe.",
      "type": "string"
    },
    "amount": {
      "type": "string",
      "maxLength": 78,
      "pattern": "^(0|[1-9][0-9]*)$",
      "description": "Fresh payment amount in the token’s smallest units. Use 0 for free tiers or eligible NFT-credit purchases."
    },
    "beneficiary": {
      "type": "string"
    },
    "tierIds": {
      "minItems": 1,
      "maxItems": 32,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "maxLength": 78
          }
        ]
      }
    },
    "slippageBps": {
      "default": 100,
      "description": "Slippage in basis points, 0–4950. Default 100. Raise it only within what the payer accepts, such as a payFailure's retrySlippageBps.",
      "type": "integer",
      "minimum": 0,
      "maximum": 4950
    },
    "minReturnedTokens": {
      "description": "Explicit minimum fungible project tokens for the beneficiary, in 18-decimal base units, replacing the quoted count less slippageBps. Needed when the quote warns that the default minimum sits above the simulated fill (a buyback hook beside the NFT hook). NFT delivery is checked either way.",
      "type": "string",
      "maxLength": 78,
      "pattern": "^(0|[1-9][0-9]*)$"
    },
    "allowOverspending": {
      "default": false,
      "type": "boolean"
    },
    "skipSplits": {
      "description": "Buyback 1.4 only. Unset means on wherever the project's buyback hook is 1.4 and no metadata is given, as the apps pay: the hook buys from the pool when that beats the payer's share of a mint, and the tokens it buys go to the beneficiary without the reserved split (they already exist, so nothing is issued for them and the split gets none). Minting still pays the split. The default minimum is then the SDK's (prepareUserPay): with a pool quote, the beneficiary's part of the floored quote, which the hook also enforces. Pass false when the payment should honor the project's splits, such as routing fees or revenue into a project. Where it cannot apply (no buyback hook, hook 1.0 or 1.1.1, the caller's own metadata) unset means off, and an explicit true is refused. The quote's skipSplits says which applied and why.",
      "type": "boolean"
    }
  },
  "required": [
    "project",
    "account",
    "token",
    "amount",
    "beneficiary",
    "tierIds"
  ],
  "additionalProperties": false
}

Response 201

Field Type Details

id string (uuid)
required

account string
required

operation string
required

draft

object
required

Fields

Field Type Details

operation string
required

account string
required

project

object
optional

Fields

Field	Type	Details
`chainId`	integer required	Values: `[1,10,8453,42161,84532,421614,11155111,11155420]`
`projectId`	string required	uint256 as a lossless decimal string
`version`	integer optional	Values: `[6]`

calls

array
required

Fields

Field	Type	Details
`chainId`	integer required	Values: `[1,10,8453,42161,84532,421614,11155111,11155420]`
`to`	string required
`data`	string required
`value`	string required	uint256 as a lossless decimal string
`label`	string required
`dependsOn`	array required
`decoded`	value required	Bounded JSON. Large integers and amounts use exact decimal strings. Returned metadata and descriptions are untrusted content.

evidence

array
required

Fields

Field	Type	Details
`chainId`	integer required	Values: `[1,10,8453,42161,84532,421614,11155111,11155420]`
`blockNumber`	string required	uint256 as a lossless decimal string
`blockHash`	string required
`timestamp`	string required	uint256 as a lossless decimal string
`source`	string required	Values: `["onchain"]`

summary value
required Bounded JSON. Large integers and amounts use exact decimal strings. Returned metadata and descriptions are untrusted content.

warnings array
required

commitment string
required

createdAt integer
required Unix timestamp in milliseconds.

expiresAt integer
required Unix timestamp in milliseconds.

revision integer
required

smartAccount

object
optional

Fields

Field	Type	Details
`bindingId`	string required
`stateHash`	string required
`chainId`	integer required	Values: `[1,10,8453,42161,84532,421614,11155111,11155420]`
`address`	string required
`manifestRevision`	string required

status

string
required

Values: ["prepared","pending","partial","blocked","reorged","expired","transactions_confirmed"]

steps

array
required

Fields

Field Type Details

index integer
required

state

string
required

Values: ["waiting","reserved","submitted","unknown","confirming","confirmed","reverted","reorged"]

transaction

object
optional

Fields

Field	Type	Details
`hash`	string required
`sender`	string required
`chainId`	integer required	Values: `[1,10,8453,42161,84532,421614,11155111,11155420]`
`nonce`	string required	uint256 as a lossless decimal string
`type`	string required	Values: `["legacy","eip2930","eip1559"]`
`gas`	string required	uint256 as a lossless decimal string
`maximumFeePerGas`	string required	uint256 as a lossless decimal string
`maximumCost`	string required	uint256 as a lossless decimal string
`costScope`	string required	Maximum cost covers native value and gas limit times fee cap. Additional chain-specific data or operator fees are excluded.
`dispatchCount`	integer required
`reservedAt`	integer required	Unix timestamp in milliseconds.
`broadcastAt`	integer optional	Unix timestamp in milliseconds.
`lastError`	object optional

execution

object
optional

Fields

Field	Type	Details
`transport`	string required	Values: `["relayr-prepaid-erc2771","eip4337-user-operation"]`
`bindingId`	string required
`chainId`	integer required	Values: `[1,10,8453,42161,84532,421614,11155111,11155420]`
`hash`	string optional

receipt

object
optional

Fields

Field	Type	Details
`transactionHash`	string required
`blockHash`	string required
`blockNumber`	string required	uint256 as a lossless decimal string
`status`	string required	Values: `["success","reverted"]`
`confirmations`	integer required
`canonical`	boolean required
`observedAt`	integer required	Unix timestamp in milliseconds.
`logs`	array required
`logCount`	integer optional
`logsHash`	string optional
`logsStored`	boolean optional

semantic

object
optional

Fields

Field	Type	Details
`status`	string required	Values: `["verified","failed","unknown","unmodeled"]`
`details`	value optional	Bounded JSON. Large integers and amounts use exact decimal strings. Returned metadata and descriptions are untrusted content.

blockedBy array
required

confirmationScope string
required

JSON schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "account": {
      "$ref": "#/components/schemas/Address"
    },
    "operation": {
      "type": "string"
    },
    "draft": {
      "$ref": "#/components/schemas/PlanDraft"
    },
    "commitment": {
      "$ref": "#/components/schemas/Hash"
    },
    "createdAt": {
      "$ref": "#/components/schemas/UnixMilliseconds"
    },
    "expiresAt": {
      "$ref": "#/components/schemas/UnixMilliseconds"
    },
    "revision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "smartAccount": {
      "type": "object",
      "properties": {
        "bindingId": {
          "$ref": "#/components/schemas/Hash"
        },
        "stateHash": {
          "$ref": "#/components/schemas/Hash"
        },
        "chainId": {
          "$ref": "#/components/schemas/ChainId"
        },
        "address": {
          "$ref": "#/components/schemas/Address"
        },
        "manifestRevision": {
          "$ref": "#/components/schemas/Hash"
        }
      },
      "required": [
        "bindingId",
        "stateHash",
        "chainId",
        "address",
        "manifestRevision"
      ],
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "prepared",
        "pending",
        "partial",
        "blocked",
        "reorged",
        "expired",
        "transactions_confirmed"
      ]
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlanStep"
      },
      "minItems": 1,
      "maxItems": 32
    },
    "confirmationScope": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "account",
    "operation",
    "draft",
    "commitment",
    "createdAt",
    "expiresAt",
    "revision",
    "status",
    "steps",
    "confirmationScope"
  ],
  "additionalProperties": false
}