Guardrails for server-side wallets

Guardrails limit what your server can sign with the wallets your project owns.

What Guardrails restrict

Your project owns some wallets outright: wallets created through the REST API, and pregenerated wallets that no user has claimed. Your backend can already sign anything with them. A Guardrail is a policy that takes cases away, so a bug or a bad input cannot make your backend sign something you never intended. Each Guardrail rule has one of these effects:

Effect	What Para does with a matching request
`deny`	Refuses to sign.
`require_approval`	Holds the request until the people named in the rule’s approval requirement approve it.
`allow`, with `actions` set to exactly `["raw_signature"]`	Nothing beyond the default, because app-owned wallets already sign raw signatures. Para still accepts this rule so older Guardrails stay valid.

Any other allow rule fails with guardrail_effect_invalid, because the wallet can already sign. Requests that no Guardrail blocks sign as usual. When several active Guardrails match a request, they all apply: deny wins over require_approval, so a block in any of them stops the request.

Guardrails apply only while a wallet belongs to your project. When a user claims a pregenerated wallet, it becomes user-owned, and Requests govern it instead. See How permissions work.

Permissions supports EVM, Solana, Cosmos, Stellar and Sui wallets. Each policy targets one wallet type, so create a separate policy for each wallet type you want rules for. A policy covers every network of its wallet type unless you list specific networks.

Before you start

You need:

A Development API key. Policies are written and tested on Development keys, which use Para’s beta environment. Production keys are read-only in the Developer Portal.
App-owned wallets created with that key, and a server that signs with them.
For require_approval rules only:
- Para must enable conditional approvals for your key. Until then, saving a policy with an approval requirement fails with permissions_v2_extension_unavailable.
- Each wallet must be bound to an authorization scope. A request that needs approval from an unbound wallet returns 403 FORBIDDEN.

Guardrails protect you from mistakes in your own code. They are not a defense against a leaked secret key, so keep the key secret and rotate it if it is exposed.

Choose how your server signs

Guardrails apply to app-owned wallets whichever SDK your server signs with, and both SDKs report the same outcomes:

	REST SDK (`@getpara/rest-sdk`)	Server SDK (`@getpara/server-sdk`)
Wallets	Wallets created through the REST API	Pregenerated wallets whose user share your server holds
A rule denies the request	`403 POLICY_DENIED`, with the rule in `deniedBy`	An error with `code: "POLICY_DENIED"`, with the rule in `error.data.deniedBy`
A rule requires approval	`403 POLICY_REVIEW_REQUIRED`, with `approvalCaseId` when the rule has an `approvalRequirement`, or `reviewId` otherwise	An error with `code: "POLICY_REVIEW_REQUIRED"`, with `error.data.approvalCaseId` when the rule has an `approvalRequirement`, or `error.data.reviewId` otherwise
Continue once approved	For a case, resend with the same `Idempotency-Key`. For an ordinary review, have your backend resolve `reviewId`, then resend the identical request.	For a case, sign again with `resumeApprovalCaseId`. For an ordinary review, have your backend resolve `reviewId`, then retry identical signing input without `resumeApprovalCaseId`.
Name the user behind a request	`initiatorUserId` in the request body	`initiatorUserId` in the signing call

The REST SDK also makes retries safe with idempotency keys. Migrate from pregenerated wallets covers the move.

A server that signs with a session imported from a signed-in user is signing that user’s wallet. Requests apply to it, not Guardrails. See How permissions work, and Review links on a server for the review that follows.

REST SDK outcomes

The REST SDK calls the REST API, so your server receives these responses. Para checks every request to the signing routes (sign-transaction, sign-message, sign-typed-data, sign-authorization and sign-raw) and to transfer against the wallet’s active Guardrails before it signs. Each response has one of four outcomes:

Outcome	Response	Next step
Signed	The route’s normal `200` response	None.
Denied	`403` with code `POLICY_DENIED`	Read `deniedBy[].reason`. Most denials repeat until the request or the policy changes. A spending-limit denial, or one caused by a value Para could not fetch, can succeed on a later try.
Approval required	`403` with code `POLICY_REVIEW_REQUIRED`	For `approvalCaseId`, wait for the approvers; for `reviewId`, resolve the ordinary review through your backend. After approval, resend the identical body with the same `Idempotency-Key`.
Spend accounting failed	`500` with code `SPEND_ACCOUNTING_FAILED`	Retry with backoff and the same `Idempotency-Key`.

Send every signing and transfer request with an Idempotency-Key taken from your own records, such as a payment ID. Para ties an approval to that key, and after a request succeeds it returns the stored response for repeats of the same key and body for 24 hours.

import { ParaRestClient, ParaRestError } from "@getpara/rest-sdk";

const para = new ParaRestClient({ apiKey: process.env.PARA_API_KEY!, env: "BETA" });

export async function sendPayment(paymentId: string, walletId: string, to: string, value: string) {
  try {
    const result = await para.transfer(walletId, { to, value, chainId: 11155111 }, { idempotencyKey: paymentId });
    return { status: "signed", result } as const;
  } catch (error) {
    if (!(error instanceof ParaRestError)) throw error;
    if (error.code === "POLICY_DENIED") return { status: "denied", body: error.body } as const;
    if (error.code === "POLICY_REVIEW_REQUIRED") return { status: "awaiting-approval", body: error.body } as const;
    throw error;
  }
}

curl -X POST "https://api.beta.getpara.com/v1/wallets/$WALLET_ID/transfer" \
  -H "X-API-Key: $PARA_API_KEY" \
  -H "Idempotency-Key: payment-4821" \
  -H "Content-Type: application/json" \
  -d '{ "to": "0x1111111111111111111111111111111111111111", "value": "1000000000000000", "chainId": 11155111 }'

ParaRestError carries the HTTP status, the code and the parsed response on body.

Signed

A request that no Guardrail stops signs as usual and returns the route’s normal response. Repeating it with the same Idempotency-Key and body returns the stored response instead of signing again.

While Permissions is on, raw signatures follow the same defaults as other signing requests: an app-owned wallet signs them, and a user-owned wallet sends them to the user for review. Rules that name the raw_signature action, and rules with "actions": "all", can change that. Raw signatures are sign-raw requests, messages from Solana, Stellar and Sui wallets, and REST sign-message requests from a Cosmos wallet that do not pass walletType: "EVM". The SDKs sign messages from Cosmos wallets as EVM sign_message requests. Raw signatures carry no network a selector can name, so only a policy without chainId governs them. A rule that names raw_signature can read only para.wallet.* facts. The Developer Portal forms cannot create one, so write it in policy JSON, with Edit JSON in the Developer Portal or with the CLI.

Denied

Para refuses to sign and returns 403. Nothing is signed or broadcast.

403 POLICY_DENIED

{
  "deniedBy": [
    {
      "policyId": "treasury-limits",
      "ruleId": "block-large-transfers",
      "reason": "matched:partner:block-large-transfers"
    }
  ],
  "code": "POLICY_DENIED",
  "message": "Transaction denied by policy"
}

deniedBy holds one entry. policyId and ruleId appear when a rule decided the outcome. Common reason values:

`reason`	Cause	What to do
`matched:partner:<ruleId>`	One of your `deny` rules matched.	Change the request, or the policy.
`matched:para:<ruleId>`	A Para rule matched.	Change the request.
`default-deny`	No rule decided the request and nothing allowed it.	Add a rule that covers the request, or change the request.
`review-rejected`	An approver rejected the approval case for this request.	Do not resend it. Start a new request if it is still needed.
`windowed-spend-limit-exceeded`	The request would take a spending limit past its cap for the current window.	Send less, or wait until the window resets. `getPartnerPolicyUsage` returns each limit’s `resetAt`.
`missing-fact`, `unknown-fact`	A rule needed a value Para could not read from this request.	Change the rule, or send a request Para can read.
`stale-fact`, `error-fact`, `resolver-error`	Para could not fetch a value a rule needed.	Retry later.
`network-unverifiable`, `coin-evidence-unverifiable`	Para could not prove the request’s network, or the coins a Sui transaction spends.	Send a request whose network Para can prove.

Para does not fall back to its defaults when it cannot read part of a request. If a rule’s condition needs a value Para cannot read, that rule is indeterminate, and the request is denied with a reason such as missing-fact unless another matching rule has the same or a stronger effect. Once an approval completes, the approved rule no longer counts as a matching rule, so an indeterminate rule can still deny the approved request. Write conditions on values that the rule’s actions always provide; the facts reference lists them.

Approval required

When the deciding rule is a require_approval rule with an approval requirement, Para opens an approval case instead of signing and returns 403:

403 POLICY_REVIEW_REQUIRED

{
  "approvalCaseId": "ca_sha256:5e0c4f2a9b1d...",
  "approvalCaseStatus": "pending",
  "artifactId": "sha256:9b2e71c4d0a6...",
  "reason": "matched:partner:approve-large-transfers",
  "code": "POLICY_REVIEW_REQUIRED",
  "message": "Transaction requires policy review"
}

string

The approval case for this request. Read its progress with getPartnerApprovalCase(approvalCaseId) or GET /v1/permissions-v2/approval-cases/{caseId}.

string

pending for a new case. When you resend a request whose case has ended, it can hold that case’s final status: completed, rejected, expired, invalidated or cancelled.

string

The rule that requires approval, as matched:<layer>:<ruleId>.

string

The ID of the policy decision Para recorded for this request. Include it when you contact Para about a decision.

The approvers named in the rule’s approval requirement decide in the Para Portal. Your secret key can read and cancel the case, but it cannot approve on anyone’s behalf.

A deciding require_approval rule without an approvalRequirement returns an ordinary reviewId. Approve or reject that review from your backend with your server secret using the review routes. Once its status is approved, resend the identical body with the same Idempotency-Key while the approval is unused, unexpired and still matches the request and policy binding.

Sponsored transfers do not support approval rules. A sponsored transfer that matches one returns 400 SPONSORSHIP_CONDITIONAL_APPROVAL_UNSUPPORTED.

Name the user behind a request

When your backend signs on behalf of one of your users, add initiatorUserId with that user’s Para user ID to the signing or transfer request. Para records the user as the requester of any approval case the request opens, and that user cannot approve or reject the case, even if the approval requirement names them.

await para.transfer(walletId, { to, value, chainId: 11155111, initiatorUserId: userId }, { idempotencyKey: paymentId });

The user must already be linked to your app. Otherwise the request fails with 400 INVALID_REQUEST and the message user is not linked to this app. Send the same initiatorUserId every time you resend the request.

Continue after approval

For a response with approvalCaseId, Para ties the case to the request’s Idempotency-Key, or to a hash of the request body when you send no key. The case stays open for up to 7 days.

Store the case with the request

Save approvalCaseId next to the Idempotency-Key and the request body.

Wait for the approvers

Poll getPartnerApprovalCase(approvalCaseId) until status is completed.

Resend the identical request

Send the same body with the same Idempotency-Key. Para evaluates it again, finds the completed case and signs. A completed case can be used for one signature.

A case that ends without approval cannot sign. If the case is rejected, expired, invalidated or cancelled, resending with the same key is refused again. To try again, send the request with a new Idempotency-Key, which opens a new case.An approval case that has not been used to sign is invalidated when the active policies that apply to its request change, for example when a policy is replaced, activated or turned off. An invalidated case cannot complete, so start a new request to open a new case.

After a POLICY_REVIEW_REQUIRED response that carries approvalCaseId, sending a different body or a different initiatorUserId with the same Idempotency-Key returns 409 CONFLICT with the message request already has a different conditional approval case.

Cancel a pending case

If you no longer need the request, cancel its case so approvers cannot approve it. Call cancelPartnerApprovalCase(approvalCaseId) in the REST SDK, or send POST /v1/permissions-v2/approval-cases/{caseId}/cancel. Only a pending case can be cancelled. The case ends with status cancelled and terminalReason case_cancelled. When a pending transaction from a user’s wallet is waiting on the case, Para discards it, so that request never signs. A request that should still go ahead needs a new attempt, which opens a new case. The new attempt needs a new Idempotency-Key. Cancelling a case that is no longer pending returns 409 CONFLICT with the message conditional approval case is not pending.

Spend accounting failed

Para could not record spend against a spending limit, for a reason other than the limit itself. It returns 500 with code SPEND_ACCOUNTING_FAILED and the message Windowed spend accounting failed, and nothing is signed. Retry with backoff, using the same Idempotency-Key and body. A request that would exceed a limit is a denial with the reason windowed-spend-limit-exceeded, not this error.

Server SDK outcomes

The server SDK signs a pregenerated wallet after you load its user share with setUserShare. When no Guardrail stops the request, signTransaction and signMessage return { signature }, as they do without Permissions. Errors from its signing worker keep their code, status and data, so your code can act on each outcome.

Handle a denial

When a policy denies the request, the signing call rejects instead of opening a review. Para’s refusal has code: "POLICY_DENIED" and status: 403. When a rule decided the denial, data.deniedBy names it with the same { policyId, ruleId, reason } entries the REST API returns. A spending limit reached while Para reserved the spend reports windowed-spend-limit-exceeded. The React Native SDK and the server SDK reject with an error object that carries this code, status and data. The object is not always an Error instance, so check its code property rather than its class.

Handle a required approval

When a deciding require_approval rule has an approvalRequirement, Para opens an approval case and the signing call throws an error with code: "POLICY_REVIEW_REQUIRED" and status: 403. error.data holds the same approvalCaseId, approvalCaseStatus, artifactId and reason fields as the REST response.

When the deciding rule requires approval without an approvalRequirement, error.data carries an ordinary reviewId. Your backend approves or rejects it with your app’s server secret through the routes in Pending transaction review. After approved, retry identical SDK signing input without resumeApprovalCaseId, only while the approval is unused and unexpired and the request and policy binding still match.

payouts.ts

import { Environment, Para as ParaServer } from "@getpara/server-sdk";

const para = new ParaServer(Environment.BETA, process.env.PARA_API_KEY!);

function readApprovalCase(error: object) {
  if (!("code" in error) || error.code !== "POLICY_REVIEW_REQUIRED") return undefined;
  if (!("data" in error) || typeof error.data !== "object" || error.data === null) return undefined;
  const data = error.data;
  if (!("approvalCaseId" in data) || typeof data.approvalCaseId !== "string") return undefined;
  if (!("approvalCaseStatus" in data) || typeof data.approvalCaseStatus !== "string") return undefined;
  return { approvalCaseId: data.approvalCaseId, approvalCaseStatus: data.approvalCaseStatus };
}

export async function signPayout(walletId: string, rlpEncodedTxBase64: string, resumeApprovalCaseId?: string) {
  try {
    const result = await para.signTransaction({ walletId, rlpEncodedTxBase64, chainId: "11155111", resumeApprovalCaseId });
    if (!("signature" in result)) throw new Error("Expected a signature for an app-owned wallet");
    return { status: "signed", signature: result.signature } as const;
  } catch (error) {
    const approvalCase = typeof error === "object" && error !== null ? readApprovalCase(error) : undefined;
    if (approvalCase) return { status: "awaiting-approval", ...approvalCase } as const;
    throw error;
  }
}

Store the approvalCaseId with the transaction. To read the case’s progress, call getPartnerApprovalCase(approvalCaseId) on a @getpara/rest-sdk client created with your secret key. Then call signPayout again with the identical transaction and the case ID. The result depends on the case:

Case status	Signing again with `resumeApprovalCaseId`
`pending`	Throws again. Para’s refusal has code `POLICY_REVIEW_REQUIRED` and `approvalCaseStatus: "pending"`.
`completed`	Signs, once per case. A case that was already used, or whose approval expired, throws instead. Para’s refusal has code `POLICY_REVIEW_REQUIRED` and `approvalCaseStatus: "completed"`.
`rejected`	Throws. Para’s refusal has code `POLICY_DENIED` and reason `review-rejected`.
`expired`, `invalidated` or `cancelled`	Throws. Para’s refusal has code `POLICY_REVIEW_REQUIRED`, and its `approvalCaseStatus` shows how the case ended.

To try again after a case has ended or been used, sign the transaction without resumeApprovalCaseId, which opens a new case. To drop a request while its case is pending, cancel the case with cancelPartnerApprovalCase(approvalCaseId) on the same REST SDK client. Pass initiatorUserId to signTransaction or signMessage to name the Para user your server is acting for. It works as it does on the REST API: the user must be linked to your app, and cannot approve or reject the case. Para reads it only for wallets your project owns.

Send the same initiatorUserId on every retry and resume of the transaction. A different or missing value fails with status 409.

The Para client and server SDKs, including their viem, ethers and wagmi integrations, sign EIP-712 typed data and EIP-7702 authorizations as a message over their hash, so Para evaluates those requests as sign_message. The sign_typed_data and sign_authorization actions, and the facts Para reads from typed data and authorizations, such as request.typedData.primaryType, apply only to the REST API’s sign-typed-data and sign-authorization routes, which the REST SDK calls.

Review links on a server

When your server signs for a signed-in user, any review opens in the Para Portal. A server has no window to open it in, so the default managed review mode fails with OpenPopup is not implemented in the ServerUtils class. Choose one of these instead:

Set transactionReviewMode: "handoff" when you create the client. The signing call returns the review link instead of waiting, and you send it to the user.
Keep managed mode and pass onTransactionReviewUrl to the signing call. The SDK hands you the link, then waits for the user’s decision as it would in a browser.

server.ts

import { Environment, Para as ParaServer } from "@getpara/server-sdk";

const para = new ParaServer(Environment.BETA, process.env.PARA_API_KEY!, {
  transactionReviewMode: "handoff",
});

export async function signForUser(serializedSession: string, walletId: string, rlpEncodedTxBase64: string) {
  await para.importSession(serializedSession);
  const result = await para.signTransaction({ walletId, rlpEncodedTxBase64, chainId: "11155111" });

  if ("signature" in result) {
    return { status: "signed", signature: result.signature } as const;
  }
  return {
    status: "needs-review",
    reviewUrl: result.transactionReviewUrl,
    pendingTransactionId: result.pendingTransactionId,
    approvalCaseId: result.approvalCaseId,
  } as const;
}

Send reviewUrl to the user. Once they approve, sign the identical transaction again to get the signature. Wallet integrations that must return a signature, such as the viem and ethers signers, throw TransactionReviewRequired in handoff mode instead, with the same transactionReviewUrl and pendingTransactionId.

Add a Guardrail

Create the policy on a Development key, run every rule against beta with your server code, then request a production review. Start in the Developer Portal; move to JSON for rules the forms cannot express.

Your production server signs as it does today until Para publishes a reviewed policy to your Production key. Guardrails you activate on a Development key change signing on beta only.

Go further

Start from a tested Guardrail, hold some requests for approval, or manage approvers and wallet bindings from your backend.

Get Started

Set Up Project

Manage Sessions

Use Pregeneration

Sign from Server

Add Permissions

Add Advanced Features

Guardrails for server-side wallets

What Guardrails restrict

Before you start

Choose how your server signs

REST SDK outcomes

Signed

Denied

Approval required

Name the user behind a request

Continue after approval

Cancel a pending case

Spend accounting failed

Server SDK outcomes

Handle a denial

Handle a required approval

Review links on a server

Add a Guardrail

Go further

​What Guardrails restrict

​Before you start

​Choose how your server signs

​REST SDK outcomes

​Signed

​Denied

​Approval required

​Name the user behind a request

​Continue after approval

​Cancel a pending case

​Spend accounting failed

​Server SDK outcomes

​Handle a denial

​Handle a required approval

​Review links on a server

​Add a Guardrail

​Go further

What Guardrails restrict

Before you start

Choose how your server signs

REST SDK outcomes

Signed

Denied

Approval required

Name the user behind a request

Continue after approval

Cancel a pending case

Spend accounting failed

Server SDK outcomes

Handle a denial

Handle a required approval

Review links on a server

Add a Guardrail

Go further