Developer API

Transfer Endpoints

Beta. Parts of what these docs describe are still being built. The roadmap shows what is live today.

These endpoints let you send transfers and look them up programmatically. Just like in the app, every transfer you create here is confidential unless you say otherwise. Privacy is the starting point, not an option you have to remember to switch on.

Send a transfer

POST /v1/transfers

Body

{
  "to": "string",
  "amount": "string",
  "asset": "USDG",
  "confidential": true,
  "memo": "string"
}

Field	Type	Required	Description
`to`	`string`	Yes	The recipient, as an `@handle` or a plain 0x address
`amount`	`string`	Yes	The amount, written as a decimal string
`asset`	`string`	No	Defaults to `USDG`
`confidential`	`boolean`	No	Defaults to `true`. Use `false` only when the recipient wallet can't handle confidential tokens.
`memo`	`string`	No	Stored encrypted, so only the sender and recipient can read it

Response

{
  "transfer_id": "tr_7f3a1c2d",
  "status": "confirmed",
  "to": "@vendor",
  "confidential": true,
  "tx_hash": "0x8f3ad41c9be2...7c1a",
  "created_at": "2026-07-02T14:23:09Z"
}

The amount you sent in the request does not come back in the response. Confidentiality applies with no exceptions: the API tells you the transfer settled, and getting the amount back means decrypting it on the client, the same as for any confidential data.

Get a transfer

GET /v1/transfers/{transfer_id}

Response

{
  "transfer_id": "tr_7f3a1c2d",
  "status": "confirmed",
  "from": "@yourname",
  "to": "@vendor",
  "confidential": true,
  "tx_hash": "0x8f3ad41c9be2...7c1a",
  "created_at": "2026-07-02T14:23:09Z",
  "confirmed_at": "2026-07-02T14:23:09Z"
}

Transfer statuses

Status	Description
`pending`	Sent to the chain and waiting for confirmation
`confirmed`	Finalized on-chain
`failed`	Did not settle, so no funds changed hands

List transfers

GET /v1/transfers

Query parameters

Parameter	Type	Default	Description
`limit`	`integer`	`20`	Number of results per page, up to `100`
`offset`	`integer`	`0`	How many results to skip for pagination
`status`	`string`	(none)	Return only transfers with this status
`from`	`string`	(none)	ISO 8601 time; returns transfers later than this
`to`	`string`	(none)	ISO 8601 time; returns transfers earlier than this

Error responses

Status	Code	Description
`400`	`invalid_request`	The body is malformed or is missing a required field
`402`	`insufficient_balance`	The account's balance of that asset is too low
`404`	`recipient_not_found`	That handle doesn't belong to any account
`422`	`recipient_not_confidential_ready`	The recipient's wallet can't receive confidential tokens. To send publicly instead, retry with `"confidential": false`

Full example

curl -X POST https://api.usecyphron.com/v1/transfers \
  -H "Authorization: Bearer hc_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "@vendor",
    "amount": "125.00",
    "asset": "USDG",
    "confidential": true,
    "memo": "Invoice #4471"
  }'