Skip to content
StablezactStablezact Docs

Create a deposit-address payment

POST
/deposits/create
curl --request POST \
  --url https://hub.stablezact.com/api/v1/deposits/create \
  --header 'Content-Type: application/json' \
  --header 'X-Public-Key: <X-Public-Key>' \
  --data '{ "amount": 1, "currency": "USDT", "network": "example", "customerEmail": "hello@example.com", "callbackUrl": "https://example.com", "orderId": "example", "metadata": { "additionalProperty": "example" }, "expiresIn": 1, "agentId": "example", "agentOwner": "example", "autonomous": true }'

Generates an address unique to this payment. The customer sends to it, and the funds are forwarded to your settlement wallet once confirmed.

A payment created this way finishes at status swept, not completed. Waiting for completed on a deposit payment means waiting forever.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
<= 200 characters

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Same core fields as creating a payment, plus the agent fields. The deposit window is a fixed fifteen minutes; see expiresIn below.

object
amount
required
One of:
number
currency

In practice only USDC and USDT are configured on any network.

string
Allowed values: USDT USDC
network

Must be a chain with deposit-address support and a settlement wallet of yours.

string
customerEmail
string format: email
callbackUrl
string format: uri
orderId
string
<= 100 characters
metadata
object
key
additional properties
string | number | boolean | null
expiresIn

Ignored. The deposit window is fixed at fifteen minutes (900 seconds) and is returned as expiresAt. It was previously settable and defaulted to twenty minutes, but the expiry job always closed deposits at fifteen, so a longer value only quoted a time that was not kept. Sending this field is accepted and has no effect.

integer
agentId

For agent-initiated payments. Must be sent with agentOwner.

string
<= 100 characters /^[a-zA-Z0-9_-]+$/
agentOwner
string
<= 100 characters
autonomous

Only permitted when the agent has a policy allowing it. Otherwise the request is refused with 403.

boolean

Responses

Section titled “Responses”

201

Section titled “201”

Payment created, with the address to send to.

Media typeapplication/json
object
success
boolean
requestId
string
payment

Includes depositAddress, expiresAt and the confirmations required.

object
Examplegenerated
{
  "success": true,
  "requestId": "example",
  "payment": {}
}

400

Section titled “400”

The request was rejected. Read error and message.

Media typeapplication/json
object
success
boolean
error
required

Short machine-ish reason.

string
message

Longer explanation, when there is one.

string
Example
{
  "success": false,
  "error": "Validation failed",
  "message": "Unsupported currency: GBP"
}

401

Section titled “401”

Missing or invalid credentials.

Media typeapplication/json
object
success
boolean
error
required

Short machine-ish reason.

string
message

Longer explanation, when there is one.

string
Example
{
  "error": "API credentials required. Use x-public-key header or x-api-key and x-api-secret headers."
}

403

Section titled “403”

The agent policy does not permit this. Either the payment exceeds the agent’s limits, or autonomous was requested without a policy allowing it.

Media typeapplication/json
object
success
boolean
error
required

Short machine-ish reason.

string
message

Longer explanation, when there is one.

string
Example
{
  "success": false
}