Skip to main content

​
Create Transaction

POST /transact
Create a new transaction to transfer currency between users.

​
Request Body

​
From
string
required
The user sending the currency
​
To
string
required
The user receiving the currency
​
Amount
uint64
required
Amount to transfer in micro-units (must be greater than 0)
​
Note
string
required
Description or note for the transaction
​
Returns
object
Optional asset returns mapping (asset ID to quantity)

​
Response

Returns 200 OK with no body on success.

​
Example Request

curl -X POST http://localhost:2009/transact \
  -H "Content-Type: application/json" \
  -d '{
    "From": "alice",
    "To": "bob",
    "Amount": 5000000,
    "Note": "Payment for services"
  }'
This transfers 5.000000 units from alice to bob.

​
Validation Errors

The endpoint validates all transactions before execution: Status Code: 400 Bad Request

​
Insufficient Balance

{
  "From": "alice",
  "To": "bob",
  "Amount": 999999999,
  "Note": "Too much money"
}
Error: insufficient balance: balance was X.XXXXXX unit, at least Y.YYYYYY unit is required

​
Missing Required Fields

{
  "From": "alice",
  "To": "bob",
  "Amount": 5000000
}
Error: transaction must have a note

​
Zero Amount Without Returns

{
  "From": "alice",
  "To": "bob",
  "Amount": 0,
  "Note": "Empty transaction"
}
Error: transaction must have an amount or returns

​
Circular Transaction

{
  "From": "alice",
  "To": "alice",
  "Amount": 5000000,
  "Note": "Self transfer"
}
Error: circular transaction: alice -> alice

​
Empty Sender or Recipient

{
  "From": "",
  "To": "bob",
  "Amount": 5000000,
  "Note": "No sender"
}
Error: transaction must have a sender

​
Get User Transactions

GET /transactions/{id}
Retrieve the last 100 transactions involving a specific user.

​
Path Parameters

​
id
string
required
The user identifier to query transactions for

​
Response

Returns a JSON array of transaction objects (up to 100 most recent).
​
transactions
array
Array of transaction objects involving the user
​
Type
string
Transaction type: "Transaction", "Mint", or "Burn"
​
Id
string
Unique 15-character transaction identifier
​
Time
uint64
Unix timestamp in milliseconds
​
From
string
Sender user ID (not present in Mint transactions)
​
To
string
Recipient user ID (not present in Burn transactions)
​
Amount
uint64
Amount in micro-units
​
Note
string
Transaction description
​
Returns
object
Asset returns if any (optional)
​
Link
string
Reference link (only in Burn transactions)

​
Example Request

curl http://localhost:2009/transactions/alice

​
Example Response

[
  {
    "Type": "Transaction",
    "Id": "abc123def456789",
    "Time": 1709481600000,
    "From": "alice",
    "To": "bob",
    "Amount": 5000000,
    "Note": "Payment for services",
    "Returns": null
  },
  {
    "Type": "Mint",
    "Id": "xyz789ghi012345",
    "Time": 1709395200000,
    "To": "alice",
    "Amount": 10000000,
    "Note": "Stipend"
  },
  {
    "Type": "Transaction",
    "Id": "mno345pqr678901",
    "Time": 1709308800000,
    "From": "charlie",
    "To": "alice",
    "Amount": 2500000,
    "Note": "Refund",
    "Returns": null
  }
]

​
Empty History

If a user has no transaction history: 
curl http://localhost:2009/transactions/newuser

[]

​
Error Responses

Status Code: 500 Internal Server Error If there’s an error reading the ledger or encoding the response, a 500 error is returned with the error message.

​
Notes

  • Transactions are returned in reverse chronological order (most recent first)
  • Maximum of 100 transactions are returned per request
  • The endpoint returns all transaction types where the user is either sender or recipient
  • Stipend transactions appear as Mint transactions with Note: “Stipend”

Build docs developers (and LLMs) love

Get started for freeTalk to us