Welcome to the SmartEscrow API! This documentation will help you understand how to programmatically create, manage, and automate secure stablecoin escrows on the blockchain.
This guide is designed for developers and covers everything from initial setup to detailed endpoint references.
Before you can make your first API call, you need to get your credentials.
The SmartEscrow API uses API Keys to authenticate requests. You can get your keys from the SmartEscrow Developer Dashboard (you will be provided a link upon partnership).
All API requests must be made over HTTPS and must include your API key in an Authorization header as a Bearer token.
Header Format:
Authorization: Bearer <YOUR_API_KEY>
Requests without a valid key will result in a 401 Unauthorized error.
Understanding these concepts is crucial for a successful integration.
Our API manages a clear, four-step process for every escrow:
This walkthrough will guide you through a complete escrow flow.
First, make a POST request to the /v1/escrows endpoint to define the agreement.
Request:
POST /v1/escrows
Host: api.smartescrow.us
Authorization: Bearer <YOUR_API_KEY>
Idempotency-Key: a1b2c3d4-e5f6-7890-1234-567890abcdef
Content-Type: application/json
{
“description”: “Escrow for NFTitle 0xabc…”,
“parties”: {
“buyer”: { “wallet_address”: “0xBUYER…” },
“seller”: { “wallet_address”: “0xSELLER…” }
},
“amount”: “10000.00”,
“stablecoin”: “uUSD”,
“blockchain”: “ethereum”,
“webhook_url”: “https://yourapp.com/webhooks/smartescrow”
}
Response (201 Created):
The API will return the full Escrow object. Most importantly, it will contain the unique escrow_wallet_address where the buyer needs to send the funds.
Instruct your buyer to send exactly 10000.00 uUSD to the escrow_wallet_address provided in the Step 1 response. Once they do, they will receive a transaction hash (TxID) from their wallet provider.
Once you have the transaction_hash from the buyer, submit it to the /fund endpoint.
Request:
POST /v1/escrows/{escrowId}/fund
Host: api.smartescrow.us
Authorization: Bearer <YOUR_API_KEY>
{
“transaction_hash”: “0x…funding_tx_hash…”
}
Response (202 Accepted):
The API acknowledges the request and begins monitoring the blockchain.
Our system will wait for sufficient on-chain confirmations. Once verified, we will send an escrow.funded event to your webhook_url. At this point, the escrow status is officially funded.
When the conditions of the sale are met, an authorized party (e.g., the buyer) can trigger the release.
Request:
POST /v1/escrows/{escrowId}/release
Host: api.smartescrow.us
Authorization: Bearer <YOUR_API_KEY>
{
“release_notes”: “Property inspection passed.”
}
Response (202 Accepted):
The API acknowledges the request and initiates the on-chain transfer to the seller’s wallet.
Once the release transaction is confirmed on the blockchain, we will send an escrow.released event to your webhook URL. The escrow is now completed.
Create a new escrow agreement.
Retrieve the details of a specific escrow.
Submit a transaction hash to prove funding.
Authorize the release of funds to the seller.
Cancel an escrow before it is released.
Our API uses standard HTTP status codes to indicate the success or failure of a request.
Code | Meaning | Description |
200 | OK | The request was successful. |
201 | Created | The resource was successfully created. |
202 | Accepted | The request was accepted for processing, but is not yet complete. |
400 | Bad Request | Your request is malformed. Check for missing parameters or invalid JSON. |
401 | Unauthorized | Your API key is missing or invalid. |
403 | Forbidden | You do not have permission to perform this action. |
404 | Not Found | The requested resource does not exist. |
500 | Internal Server Error | We had a problem with our server. Please try again later. |
Webhooks are the recommended way to get notified about events happening with your escrows.
All webhook events are sent as a POST request to your specified webhook_url with the following JSON structure:
{
“event_id”: “evt_zxyw987…”,
“event_type”: “escrow.funded”,
“created_at”: “2025-09-16T14:45:10Z”,
“data”: {
“object”: {
// The full Escrow or Transaction object
}
}
}
Your endpoint must respond with a 200 OK status code to acknowledge that you have received the webhook. If we do not receive a 200 OK, we will consider the delivery a failure and retry with an exponential backoff schedule.