POST /api/v1/operations/{id}/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. |
id | path / required | string
|
Request body
Option 1
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
memo | string optional | |||||||||||||
project | object required | Fields
| ||||||||||||
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: | ||||||||||||
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. |
Option 2
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
holder | string required | |||||||||||||
cashOutCount | string required | Project token count in 18-decimal base units. | ||||||||||||
tokenToReclaim | string required | Token address; native ETH is 0x000000000000000000000000000000000000EEEe. | ||||||||||||
beneficiary | string required | |||||||||||||
account | string required | |||||||||||||
slippageBps | integer optional | Slippage in basis points, 0–1000. Default 100 (1%). Default: | ||||||||||||
terminal | string optional |
Option 3
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
token | string required | Token address; native ETH is 0x000000000000000000000000000000000000EEEe. | ||||||||||||
amount | string required | Payout amount in accounting token decimals, denominated in currency. | ||||||||||||
currency | integer 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. | ||||||||||||
slippageBps | integer optional | Slippage in basis points, 0–1000. Default 100 (1%). Default: | ||||||||||||
terminal | string optional |
Option 4
| Field | Type | Details | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| |||||||||||||||||||||||||||
account | string required | ||||||||||||||||||||||||||||
rulesetConfigurations | array required | Fields
| |||||||||||||||||||||||||||
memo | string optional |
Option 5
| Field | Type | Details | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
chainId | one of required | ||||||||||||||||||||||||||||
account | string required | ||||||||||||||||||||||||||||
owner | string required | ||||||||||||||||||||||||||||
composition | string required | Explicit standard core launch. This does not deploy a 721 hook, revnet, or omnichain identity. Values: | |||||||||||||||||||||||||||
projectUri | string required | Metadata URI; content is not fetched or treated as instructions. | |||||||||||||||||||||||||||
rulesetConfigurations | array required | Fields
| |||||||||||||||||||||||||||
terminalConfigurations | array required | Fields
| |||||||||||||||||||||||||||
memo | string optional |
Option 6
| Field | Type | Details | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
chainIds | array required | Every chain the project launches on, all mainnets or all testnets. | |||||||||||||||||||||||||||
account | string required | The one address that signs on every chain. | |||||||||||||||||||||||||||
owner | string required | ||||||||||||||||||||||||||||
projectUri | string required | Pinned metadata URI (ipfs://<cid>), or empty to set it later. | |||||||||||||||||||||||||||
rulesetConfigurations | array required | Fields
| |||||||||||||||||||||||||||
terminalConfigurations | array required | Fields
| |||||||||||||||||||||||||||
memo | string optional | Default: | |||||||||||||||||||||||||||
salt | string required | One random salt shared by every chain. Suckers pair only with the same salt and signer. | |||||||||||||||||||||||||||
bridge | string optional | ccip links any chain pair. native links Ethereum with one L2 and maps native ETH only. both adds a native sucker where one exists. Values: Default: | |||||||||||||||||||||||||||
deployTiersHookConfig | object optional | NFT tiers collection. Omitted: an empty collection priced in the first baseCurrency.Fields
| |||||||||||||||||||||||||||
useDataHookForCashOut | boolean optional | Let NFTs cash out for surplus. Needs deployTiersHookConfig. Default: |
Option 7
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | The address that will sign. | ||||||||||||
name | string required | ERC-20 name, such as "Lattice". | ||||||||||||
symbol | string required | ERC-20 symbol (ticker), such as "LATT". | ||||||||||||
salt | string optional | Zero for a one-off address. A nonzero salt gives a deterministic address from this salt and the signer; use the same salt and signer on every chain to get the same token address. |
Option 8
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | The address that will sign. | ||||||||||||
uri | string required | Metadata URI the user already pinned, as ipfs://<cid> (jb_pin_project_metadata returns one). Not fetched. |
Option 9
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
holder | string required | |||||||||||||
token | string required | Token address; native ETH is 0x000000000000000000000000000000000000EEEe. | ||||||||||||
collateralCount | string required | Project tokens to lock as collateral, with 18 decimals: 1000000000000000000 = 1 token. The holder must hold them; the loan burns them and mints them back on repay. | ||||||||||||
prepaidFeePercent | integer required | Fee prepaid at borrow time, out of 1,000. Allowed 25 (2.5%) to 500 (50%). | ||||||||||||
beneficiary | string required | |||||||||||||
account | string required | |||||||||||||
slippageBps | integer optional | Slippage in basis points, 0–1000. Default 100 (1%). Default: |
Option 10
| Field | Type | Details |
|---|---|---|
chainId | one of required | |
loanId | string required | |
account | string required | |
maxRepayBorrowAmount | string required | |
collateralCountToReturn | string required | |
beneficiary | string required |
Option 11
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
sucker | string required | |||||||||||||
claim | object required | Fields
|
Option 12
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
sucker | string required | |||||||||||||
maxTransportValue | string required | Maximum native wei attached to the accounting message; gas is additional. |
Option 13
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
terminalToken | string required | Token address; native ETH is 0x000000000000000000000000000000000000EEEe. | ||||||||||||
fee | integer required | Static Uniswap V4 pool fee in hundredths of a basis point; 3000 = 0.3%. | ||||||||||||
tickSpacing | integer required | |||||||||||||
twapWindowSeconds | integer required | The current hook maps registration at 172800 to its 1800-second default; retired 1.1.1 and v1 hooks store 172800 unchanged. Use the TWAP update tool afterward for an explicit 172800-second window on the current hook. |
Option 14
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
terminalToken | string required | Token address; native ETH is 0x000000000000000000000000000000000000EEEe. | ||||||||||||
twapWindowSeconds | integer required |
Option 15
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
hook | string required |
Option 16
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
terminal | string required |
Option 17
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
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: | ||||||||||||
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: | ||||||||||||
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. |
Option 18
| Field | Type | Details | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||||||||||||||||||||||||||
account | string required | |||||||||||||||||||||||||||||||||||||
tiersToAdd | array required | Fields
| ||||||||||||||||||||||||||||||||||||
tierIdsToRemove | array required |
Option 19
| Field | Type | Details | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
chainId | one of required | ||||||||||||||||||||||||||||
account | string required | ||||||||||||||||||||||||||||
owner | string required | ||||||||||||||||||||||||||||
deployTiersHookConfig | object required | Fields
| |||||||||||||||||||||||||||
projectUri | string required | ||||||||||||||||||||||||||||
rulesetConfigurations | array required | Fields
| |||||||||||||||||||||||||||
terminalConfigurations | array required | Fields
| |||||||||||||||||||||||||||
memo | string optional | Default: | |||||||||||||||||||||||||||
salt | string required |
Option 20
| Field | Type | Details | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
chainId | one of required | ||||||||||||||||||||||
account | string required | ||||||||||||||||||||||
config | object required | Fields
| |||||||||||||||||||||
accountingContexts | array required | Fields
| |||||||||||||||||||||
chainIds | array optional | Every chain the revnet launches on, including chainId. Instead of suckerConfig: the sucker registry fills the bridges to the other chains, salted with config.description.salt, mapping native ETH and USDC when accepted. | |||||||||||||||||||||
bridge | string optional | With chainIds. Default ccip. ccip links any chain pair. native links Ethereum with one L2 and maps native ETH only. both adds a native sucker where one exists. Values: | |||||||||||||||||||||
suckerConfig | object optional | Explicit bridges, instead of chainIds. Use { salt, deployerConfigurations: [] } for one chain.Fields
| |||||||||||||||||||||
tiered721Config | object optional | Fields
| |||||||||||||||||||||
allowedPosts | array optional | Fields
|
Option 21
| Field | Type | Details | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
project | object required | Fields
| ||||||||||||
account | string required | |||||||||||||
stageId | string required | |||||||||||||
beneficiary | string required |
JSON schema
{
"oneOf": [
{
"$ref": "#/components/schemas/OperationInput_prepare_pay"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_cash_out"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_payout"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_ruleset_change"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_launch"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_omnichain_launch"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_deploy_erc20"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_set_project_uri"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_borrow"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_repay"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_bridge_claim"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_accounting_sync"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_buyback_pool"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_buyback_twap"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_buyback_hook"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_router_terminal"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_721_pay"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_adjust_tiers"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_721_launch"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_revnet_deploy"
},
{
"$ref": "#/components/schemas/OperationInput_prepare_auto_issue"
}
]
}Response 201
| Field | Type | Details | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string (uuid) required | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
account | string required | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
operation | string required | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
draft | object required | Fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
commitment | string required | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAt | integer required | Unix timestamp in milliseconds. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
expiresAt | integer required | Unix timestamp in milliseconds. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
revision | integer required | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
smartAccount | object optional | Fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
status | string required | Values: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
steps | array required | Fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
}