Skip to main content
POST
/
api
/
ledger
/
v2
/
{ledger}
/
transactions
Create a new transaction to a ledger
curl --request POST \
  --url http://localhost/api/ledger/v2/{ledger}/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "admin": "true"
  },
  "timestamp": "2023-11-07T05:31:56Z",
  "postings": [
    {
      "amount": 100,
      "asset": "COIN",
      "destination": "users:002",
      "source": "users:001"
    }
  ],
  "script": {
    "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
    "vars": {
      "user": "users:042"
    }
  },
  "runtime": "experimental-interpreter",
  "reference": "ref:001",
  "accountMetadata": {},
  "force": true
}
'
{
  "data": {
    "timestamp": "2023-11-07T05:31:56Z",
    "postings": [
      {
        "amount": 100,
        "asset": "COIN",
        "destination": "users:002",
        "source": "users:001"
      }
    ],
    "metadata": {
      "admin": "true"
    },
    "id": 1,
    "reverted": true,
    "insertedAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "reference": "ref:001",
    "revertedAt": "2023-11-07T05:31:56Z",
    "preCommitVolumes": {
      "orders:1": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      },
      "orders:2": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      }
    },
    "postCommitVolumes": {
      "orders:1": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      },
      "orders:2": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      }
    },
    "preCommitEffectiveVolumes": {
      "orders:1": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      },
      "orders:2": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      }
    },
    "postCommitEffectiveVolumes": {
      "orders:1": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      },
      "orders:2": {
        "USD": {
          "input": 100,
          "output": 10,
          "balance": 90
        }
      }
    }
  }
}
Create a new transaction to transfer value between accounts. This is the core operation of the ledger. Using Numscript: 
{
  "script": {
    "plain": "send [USD/2 10000] (
  source = @user:john:wallet allowing unbounded overdraft
  destination = @user:mary:wallet
)"
  },
  "reference": "payment-001"
}
Using Postings: 
{
  "postings": [
    {
      "source": "world",
      "destination": "user:alice:wallet",
      "amount": 5000,
      "asset": "USD/2"
    }
  ],
  "reference": "deposit-001"
}

​
Parameters

ledger: The name of the ledger to create the transaction in. (e.g., ledger001) dryRun: When true, validates the transaction without persisting it. Useful for testing Numscript logic before committing. (e.g., true) Idempotency-Key: A unique key to ensure the request is processed exactly once. If you retry a request with the same key, the original transaction is returned instead of creating a duplicate. (e.g., tx-abc-123) force: When true, allows accounts to go negative (overdraft). By default, transactions fail if a source account has insufficient funds.

​
Request Body

The transaction definition. Use script for Numscript or postings for explicit transfers. See examples above.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
Idempotency-Key
string

Use an idempotency key

Path Parameters

​
ledger
string
required

Name of the ledger.

Example:

"ledger001"

Query Parameters

​
dryRun
boolean

Set the dryRun mode. dry run mode doesn't add the logs to the database or publish a message to the message broker.

Example:

true

​
force
boolean

Disable balance checks when passing postings

Example:

true

Body

application/json

The request body must contain at least one of the following objects:

  • postings: suitable for simple transactions
  • script: enabling more complex transactions with Numscript
​
metadata
object
required
Example:
{ "admin": "true" }
​
timestamp
string<date-time>
​
postings
object[]
​
script
object
​
runtime
enum<string>

The numscript runtime used to execute the script. Uses "machine" by default, unless the "--experimental-numscript-interpreter" feature flag is passed.

Available options:
experimental-interpreter,
machine
​
reference
string
Example:

"ref:001"

​
accountMetadata
object
​
force
boolean

Response

OK

​
data
object
required