Extend TTL

Extend the escrow contract storage TTL before it expires, signed by the escrow admin.

Soroban storage has a finite time-to-live: without periodic extension the escrow state expires and becomes unreadable until restored. This endpoint builds the unsigned transaction that extends it, signed by the escrow admin (roles.admin).

The reference below is generated from the live API spec — if anything on this page disagrees with it, the reference wins.

Endpoint

Extend the contract's storage TTL by N ledgers

post

Soroban storage TTL is finite; without periodic extension the escrow state expires. Only the admin (per-escrow) can call this in V2.

Authorizations

x-api-keystringRequired

Body

contractIdstringRequired

Deployed v2 escrow contract (C...).

Example: CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB

adminstringRequired

Admin wallet authorising the TTL extension — must equal the on-chain roles.admin. Signs the transaction.

Example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

ledgersToExtendnumberRequired

Ledgers to extend the contract's storage TTL. Maps to a u32 on-chain.

Example: 100000

Responses

200

Unsigned XDR built successfully.

application/json

unsignedXdrstringRequired

Base64-encoded unsigned XDR. Sign it with the appropriate wallet and submit to Soroban / Horizon to execute the operation on-chain.

Example: AAAAAgAAAAAtWsgedQ...AAAAAQAAAAA=

txHashstringRequired

SHA-256 hash of the prepared transaction. NOTE: it only matches the executed transaction if you sign the XDR exactly as returned — re-preparing (re-simulating) it changes the hash. Prefer contractId for correlation when present.

Example: b1946ac92492d2347c6235b4d2611184a8d53f7a8e6e9b4f0c79a2b30e5c4f3a

contractIdobject · nullableOptional

Deploys only: the address (C…) the new escrow contract WILL have once this transaction executes — known upfront because the service generates the deploy salt. Track your escrow with it (e.g. GET /escrows/:contractId) as soon as the transaction lands; it is stable even if your wallet/SDK re-prepares the transaction.

Example: CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526

400

Request body or query params fail schema validation (wrong type, missing required field, unknown property).

application/json

401

Missing, malformed, expired, revoked or invalid API key.

application/json

403

API key is valid but does not have the role required for this operation.

application/json

422

Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).

application/json

500

Unexpected server-side failure. Use the traceId to look up the incident in server logs or contact support.

application/json

post/escrow/single-release/v2/extend-ttl

POST /escrow/single-release/v2/extend-ttl HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 165

{
  "contractId": "CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB",
  "admin": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
  "ledgersToExtend": 100000
}

{
  "unsignedXdr": "AAAAAgAAAAAtWsgedQ...AAAAAQAAAAA=",
  "txHash": "b1946ac92492d2347c6235b4d2611184a8d53f7a8e6e9b4f0c79a2b30e5c4f3a",
  "contractId": "CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526"
}

Field notes

• ledgersToExtend is a u32 (max 4294967295); one ledger ≈ 5 seconds on testnet/mainnet.

• Already expired? The build returns 409 with code STELLAR_STATE_ARCHIVED and a ready-to-sign restoreXdr in the error's extensions. Sign and submit that restore transaction first (it must go alone — one Soroban operation per transaction), then retry the extend.

What this endpoint returns

unsignedXdr + txHash — sign the XDR exactly as returned and submit it via Send Transaction.