POST /api/v1/operations/prepare_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

memo string
optional

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 Input asset amount in its smallest units, as an exact integer string.

beneficiary string
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 project tokens for the beneficiary, in 18-decimal base units, replacing beneficiaryTokenCount less slippageBps. To accept 2% below the fill, take the quote's simulatedBeneficiaryTokenCount less 2%. A warning names a figure above the simulated fill. jb_prepare_pay requires it when the default would protect nothing (PAY_MINIMUM_PROTECTS_NOTHING) or sits above the simulated fill (PAY_DEFAULT_MINIMUM_ABOVE_FILL). "0" accepts receiving no project tokens.

metadata string
optional

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": {
    "memo": {
      "type": "string"
    },
    "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": "Input asset amount in its smallest units, as an exact integer string."
    },
    "beneficiary": {
      "type": "string"
    },
    "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 project tokens for the beneficiary, in 18-decimal base units, replacing beneficiaryTokenCount less slippageBps. To accept 2% below the fill, take the quote's simulatedBeneficiaryTokenCount less 2%. A warning names a figure above the simulated fill. jb_prepare_pay requires it when the default would protect nothing (PAY_MINIMUM_PROTECTS_NOTHING) or sits above the simulated fill (PAY_DEFAULT_MINIMUM_ABOVE_FILL). \"0\" accepts receiving no project tokens.",
      "type": "string",
      "maxLength": 78,
      "pattern": "^(0|[1-9][0-9]*)$"
    },
    "metadata": {
      "type": "string",
      "maxLength": 262146,
      "pattern": "^0x(?:[a-fA-F0-9]{2})*$"
    },
    "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"
  ],
  "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
}