Prepare Escrow Payment
prepare_escrow_paymentWork out where a payment must go, before anybody signs or sends anything.
seller and nominal_buyer may each be a wallet address OR AN EMAIL ADDRESS — an email is
converted to the wallet that person owns, so you never need to know a wallet to use this.
Returns the escrow address these terms produce, and TWO ways to fund it. Both end at the same address holding the same money; they differ only in who sends the transaction.
Transfer it yourself. Send the tokens to the address from any wallet — a browser
wallet, a hardware wallet, an exchange withdrawal. Nothing to sign for us, and no payer
needed, because the escrow never asks who paid: it reads its own balance. Then call
settle_escrow_payment with no signature and we create the escrow around what is there.
Or let us relay it. Pass payer and this returns an EIP-3009 authorization for them to
sign. We broadcast it and pay the gas, so the payer needs no gas at all. This is the
only one an agent can complete unattended, and the only one that needs a key anywhere.
Either way the address is the same, because it is a pure function of the terms. That is
also what makes the relayed form safe: the payer signs to as part of the authorization,
committing to every term at once — alter any of them afterwards and the address moves and
the signature stops matching.
amount is in the TOKEN's base units (1 USDC = 1000000), because that exact figure is one
of the terms the address derives from.
expiry_timestamp is an absolute Unix time — when the dispute window closes. 0 settles
instantly with no recourse. There is no default: "instant, deliberately" and "nobody said"
are different, and a caller must not discover afterwards which one they got.
nominal_buyer is who may dispute and receives a refund. For an agentic payment this should
be the PERSON, not the agent — they are the one who will later read a report and decide
whether to object.
seller and nominal_buyer may each be a wallet address OR an email address. An email
resolves to the wallet Privy holds for that person — made for them if they have never
logged in — and the same email always resolves to the same wallet, so the address derived
here is the one settle_escrow_payment derives too. The resolved wallets come back under
parties. A seller given by email is paid into that wallet; they sign in with the email to
reach it.
external_id keeps two otherwise-identical payments apart, and is one of the terms the
address derives from. Leave it out and a unique one is generated. That is the right
default: two payments matching in seller, amount, maturity and buyer would otherwise derive
to the SAME address, and funding the second sends money into the first escrow — recoverable
only after that one is claimed, and only to ITS buyer.
⚠️ PASS BACK THE external_id THIS RETURNS, not the one you sent. A generated one is only
knowable from the result, and settle derives the address again from whatever it is given:
a different id is a different address, and the money is at this one.
Supply your own for the opposite behaviour — a checkout hash gives "one checkout, one escrow", so re-presenting the same purchase returns the same address rather than a second.
description is what the payment is FOR, in the buyer's own words — ask them for it rather
than defaulting. It is what they will be looking at in the dashboard weeks later deciding
whether to dispute, and "Escrow payment" tells them nothing about which one this was. It
does not affect the address, so it can be set freely here.
⚠️ 1 to 160 characters. Longer is refused HERE rather than at the chain, where the check happens after the money has already moved.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| payer | No | ||
| amount | Yes | ||
| seller | Yes | Who gets paid: a wallet address (0x…) OR an email address. An email is converted to the wallet that person owns, created for them if they have never signed in; the same email always gives the same wallet. | |
| description | No | Escrow payment | |
| external_id | No | ||
| token_symbol | No | USDC | |
| nominal_buyer | Yes | Who may dispute and receives any refund — the PERSON, not the agent: a wallet address (0x…) OR an email address. An email is converted to that person's wallet, created for them if they have never signed in. | |
| expiry_timestamp | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||