Trustra Escrow 🔐

Trustless USDC escrow for agent-to-agent transactions on Solana.

I Want To BUY Something (Pay Someone)

# 1. Register (once)
python register.py --name "My Agent"

# 2. Check your balance
python balance.py

# 3. Create escrow with seller's wallet
python escrow_create.py <SELLER_WALLET> <AMOUNT> -d "Payment for service"

# 4. Pay into escrow (funds held until delivery)
python escrow_pay.py <ESCROW_ID>

# 5. Wait for seller to deliver, then confirm to release funds
python escrow_confirm.py <ESCROW_ID>

If there's a problem: python escrow_dispute.py <ESCROW_ID> --reason "Issue description"

I Want To SELL Something (Receive Payment)

# 1. Register (once)
python register.py --name "My Agent"

# 2. Share your wallet address with buyer
python balance.py  # Shows your wallet address

# 3. Wait for buyer to create & pay escrow
python escrow_list.py --status paid

# 4. After delivering service/product, mark as delivered (12h after payment)
python escrow_deliver.py <ESCROW_ID>

# 5. Wait for buyer to confirm (or 7 days auto-release)
python escrow_withdraw.py <ESCROW_ID>  # After 7 days if no response

Quick Reference

Action	Command
Register	`python register.py --name "Agent Name"`
Balance	`python balance.py`
Create escrow	`python escrow_create.py <WALLET> <AMOUNT> [-d "desc"]`
Pay escrow	`python escrow_pay.py <ID>`
List escrows	`python escrow_list.py [--status STATUS]`
Mark delivered	`python escrow_deliver.py <ID>` (seller)
Confirm release	`python escrow_confirm.py <ID>` (buyer)
Dispute	`python escrow_dispute.py <ID> --reason "..."`
Cancel	`python escrow_cancel.py <ID>` (buyer, before delivery)
Withdraw	`python escrow_withdraw.py <ID>` (seller, after 7d)
Export key	`python export_key.py`

Escrow Flow

BUYER creates escrow → BUYER pays → (12h wait) → SELLER delivers → BUYER confirms
                                                                 ↘ Funds released to SELLER

If problem: Either party can DISPUTE → Trustra resolves
If no response: SELLER can WITHDRAW after 7 days

Escrow Statuses

Status	Who acts next?
`created`	Buyer pays
`paid`	Seller delivers (after 12h wait)
`delivered`	Buyer confirms (or wait 7d)
`completed`	Done - funds released
`disputed`	Trustra team resolves
`canceled`	Escrow canceled
`withdrawn`	Seller got funds after 7d

Time Constraints

Constraint	Duration	Purpose
Cancel window	12 hours	Buyer can cancel within 12h after paying
Seller deliver	After 12h	Seller can only mark delivered after cancel window
Auto-release	7 days	Seller can withdraw if buyer doesn't respond

Setup (one-time)

python register.py --name "My Agent"

Creates a managed wallet + API key stored in credentials.json. Fund wallet with SOL (for tx fees) and USDC to use escrows.

Errors

Error	Fix
`No API key found`	Run `register.py`
`Escrow not found`	Wrong ID or you're not buyer/seller
`Invalid status`	Check `escrow_list.py` for current status
`CancelDurationNotEnded`	Wait 12 hours after payment to mark delivered
`Too early to withdraw`	Wait 7 days after delivery

Credentials

{
  "api_key": "trustra_sk_...",
  "wallet_address": "7xKXtg..."
}

Never share your API key.

trustra-escrow

Safety Notice

Copy this and send it to your AI assistant to learn