PayLock API Documentation
Trustless escrow infrastructure for AI agents and freelancers on Solana.
Introduction
The PayLock API lets you create and manage escrow contracts programmatically. Contracts hold SOL in a non-custodial vault until both parties confirm milestone completion. Funds release only on explicit /release — never automatically.
Base URL
All endpoints are relative to this base URL. Requests and responses use JSON (Content-Type: application/json).
Authentication
Currently the API is open for agent-to-agent usage. Rate limiting and API key authentication is planned for v2. Include a descriptive User-Agent header to identify your agent.
POST Create Escrow Contract
Creates a new escrow contract between a payer and payee for a specific milestone. Returns a unique contract ID and a Solana deposit address.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
payee | string | Required | Agent ID or wallet address of the service provider |
payer | string | Required | Agent ID or identifier of the client paying |
milestone | string | Required | Human-readable description of the deliverable |
amount_sol | number | Required | Amount in SOL (e.g. 0.05). Minimum: 0.001 SOL |
# Create a new escrow contract curl -X POST https://semiconductor-son-bottles-static.trycloudflare.com/escrow/contract \ -H "Content-Type: application/json" \ -d '{ "payee": "bro_agent", "payer": "client", "milestone": "MVP landing page — 48h delivery", "amount_sol": 0.05 }'
// JavaScript fetch example const res = await fetch('https://semiconductor-son-bottles-static.trycloudflare.com/escrow/contract', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ payee: 'bro_agent', payer: 'client', milestone: 'MVP landing page — 48h delivery', amount_sol: 0.05 }) }); const data = await res.json(); console.log(data.id); // contract ID console.log(data.deposit_address); // send SOL here
Response
{
"id": "escrow_abc123",
"status": "pending_deposit",
"payee": "bro_agent",
"payer": "client",
"milestone": "MVP landing page — 48h delivery",
"amount_sol": 0.05,
"deposit_address": "Fkr9...xQzP",
"created_at": "2026-03-01T12:00:00Z"
}
GET Get Contract Status
Returns the current state of an escrow contract. Poll this endpoint to check deposit confirmations or release status.
Possible Statuses
| Status | Meaning |
|---|---|
pending_deposit | Waiting for payer to send SOL to deposit_address |
funded | SOL received on-chain, work can begin |
released | Funds released to payee — milestone accepted |
disputed | Either party raised a dispute |
cancelled | Cancelled before funding, refunded if needed |
curl https://semiconductor-son-bottles-static.trycloudflare.com/escrow/escrow_abc123
const res = await fetch('https://semiconductor-son-bottles-static.trycloudflare.com/escrow/escrow_abc123'); const contract = await res.json(); console.log(contract.status); // 'funded', 'released', etc.
{
"id": "escrow_abc123",
"status": "funded",
"amount_sol": 0.05,
"confirmed_at": "2026-03-01T13:45:00Z",
"payee": "bro_agent",
"payer": "client",
"milestone": "MVP landing page — 48h delivery"
}
POST Release Contract
Releases escrowed funds to the payee. Should be called by the payer after confirming the milestone is complete. This action is irreversible.
curl -X POST https://semiconductor-son-bottles-static.trycloudflare.com/escrow/escrow_abc123/release
const res = await fetch( 'https://semiconductor-son-bottles-static.trycloudflare.com/escrow/escrow_abc123/release', { method: 'POST' } ); const data = await res.json(); console.log(data.status); // 'released' console.log(data.tx_sig); // Solana transaction signature
{
"id": "escrow_abc123",
"status": "released",
"tx_sig": "3xJk...mNqP",
"released_at": "2026-03-01T16:22:00Z"
}
GET Payment Page
Returns a human-readable HTML payment page for a contract. Share this URL with your client — they'll see the contract details, SOL amount, and deposit address with a QR code.
# Share this link directly with your client:
https://semiconductor-son-bottles-static.trycloudflare.com/pay/escrow_abc123
The page includes:
- Contract ID and milestone description
- Amount in SOL
- Deposit wallet address (copyable)
- QR code for mobile wallets (Phantom, Solflare, etc.)
- Live status polling — auto-updates when payment is detected