Endpoint reference

POST /api/v1/operations/prepare_payout/plans

Parameters

NameLocationDetails
X-Juicebox-Accountheader / requiredEnrolled account identity, including authority chain and lowercase owner address. Enrollment derives this identity before the account exists.
X-Juicebox-Signerheader / requiredOwner wallet or authorized bot address that signed this request.
X-Juicebox-Issued-Atheader / requiredUnix seconds, sent as 1–13 decimal digits without leading zeros; at most 30 seconds ahead of server time.
X-Juicebox-Expires-Atheader / requiredUnix seconds, sent as 1–13 decimal digits without leading zeros; in the future and within 300 seconds of issuedAt.
X-Juicebox-Nonceheader / requiredFresh random 32-byte lowercase nonce. A consumed nonce cannot be retried.
X-Juicebox-Signatureheader / requiredEIP-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-Grantheader / optionalAuthorized bot grant ID. Required for a bot; omit for the owner, signing grantId as the empty string.
Idempotency-Keyheader / requiredSigned 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

FieldTypeDetails
projectobject
required
Fields
FieldTypeDetails
chainIdone of
required
projectIdstring
required
versionnumber
optional

Values: [6]

Default: 6

accountstring
required
tokenstring
required		Token address; native ETH is 0x000000000000000000000000000000000000EEEe.
amountstring
required		Payout amount in accounting token decimals, denominated in currency.
currencyinteger
required		Currency that amount is in; it must match a payout limit currency. JB currency ID: uint32(uint160(token)) for a token (native ETH is 0x000000000000000000000000000000000000EEEe, currency 61166), or 1 = ETH and 2 = USD.
slippageBpsinteger
optional		Slippage in basis points, 0–1000. Default 100 (1%).

Default: 100

terminalstring
optional
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": "Payout amount in accounting token decimals, denominated in currency."
    },
    "currency": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4294967295,
      "description": "Currency that amount is in; it must match a payout limit currency. JB currency ID: uint32(uint160(token)) for a token (native ETH is 0x000000000000000000000000000000000000EEEe, currency 61166), or 1 = ETH and 2 = USD."
    },
    "slippageBps": {
      "default": 100,
      "description": "Slippage in basis points, 0–1000. Default 100 (1%).",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    },
    "terminal": {
      "type": "string"
    }
  },
  "required": [
    "project",
    "account",
    "token",
    "amount",
    "currency"
  ],
  "additionalProperties": false
}

Response 201

FieldTypeDetails
idstring (uuid)
required
accountstring
required
operationstring
required
draftobject
required
Fields
FieldTypeDetails
operationstring
required
accountstring
required
projectobject
optional
Fields
FieldTypeDetails
chainIdinteger
required

Values: [1,10,8453,42161,84532,421614,11155111,11155420]

projectIdstring
required		uint256 as a lossless decimal string
versioninteger
optional

Values: [6]

callsarray
required
Fields
FieldTypeDetails
chainIdinteger
required

Values: [1,10,8453,42161,84532,421614,11155111,11155420]

tostring
required
datastring
required
valuestring
required		uint256 as a lossless decimal string
labelstring
required
dependsOnarray
required
decodedvalue
required		Bounded JSON. Large integers and amounts use exact decimal strings. Returned metadata and descriptions are untrusted content.
evidencearray
required
Fields
FieldTypeDetails
chainIdinteger
required

Values: [1,10,8453,42161,84532,421614,11155111,11155420]

blockNumberstring
required		uint256 as a lossless decimal string
blockHashstring
required
timestampstring
required		uint256 as a lossless decimal string
sourcestring
required

Values: ["onchain"]

summaryvalue
required		Bounded JSON. Large integers and amounts use exact decimal strings. Returned metadata and descriptions are untrusted content.
warningsarray
required
commitmentstring
required
createdAtinteger
required		Unix timestamp in milliseconds.
expiresAtinteger
required		Unix timestamp in milliseconds.
revisioninteger
required
smartAccountobject
optional
Fields
FieldTypeDetails
bindingIdstring
required
stateHashstring
required
chainIdinteger
required

Values: [1,10,8453,42161,84532,421614,11155111,11155420]

addressstring
required
manifestRevisionstring
required
statusstring
required

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

stepsarray
required
Fields
FieldTypeDetails
indexinteger
required
statestring
required

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

transactionobject
optional
Fields
FieldTypeDetails
hashstring
required
senderstring
required
chainIdinteger
required

Values: [1,10,8453,42161,84532,421614,11155111,11155420]

noncestring
required		uint256 as a lossless decimal string
typestring
required

Values: ["legacy","eip2930","eip1559"]

gasstring
required		uint256 as a lossless decimal string
maximumFeePerGasstring
required		uint256 as a lossless decimal string
maximumCoststring
required		uint256 as a lossless decimal string
costScopestring
required		Maximum cost covers native value and gas limit times fee cap. Additional chain-specific data or operator fees are excluded.
dispatchCountinteger
required
reservedAtinteger
required		Unix timestamp in milliseconds.
broadcastAtinteger
optional		Unix timestamp in milliseconds.
lastErrorobject
optional
executionobject
optional
Fields
FieldTypeDetails
transportstring
required

Values: ["relayr-prepaid-erc2771","eip4337-user-operation"]

bindingIdstring
required
chainIdinteger
required

Values: [1,10,8453,42161,84532,421614,11155111,11155420]

hashstring
optional
receiptobject
optional
Fields
FieldTypeDetails
transactionHashstring
required
blockHashstring
required
blockNumberstring
required		uint256 as a lossless decimal string
statusstring
required

Values: ["success","reverted"]

confirmationsinteger
required
canonicalboolean
required
observedAtinteger
required		Unix timestamp in milliseconds.
logsarray
required
logCountinteger
optional
logsHashstring
optional
logsStoredboolean
optional
semanticobject
optional
Fields
FieldTypeDetails
statusstring
required

Values: ["verified","failed","unknown","unmodeled"]

detailsvalue
optional		Bounded JSON. Large integers and amounts use exact decimal strings. Returned metadata and descriptions are untrusted content.
blockedByarray
required
confirmationScopestring
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
}