Create a new transaction to a ledger

POST /api/ledger/v2/{ledger}/transactions

Try it

Create a new transaction to a ledger

cURL

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
}
'

200

{
  "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
        }
      }
    }
  }
}

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

Show child attributes

metadata. {key} · string

Example:

{ "admin": "true" }

timestamp · string<date-time>

postings · object[]

Show child attributes

postings. amount · integer<bigint> · required

Required range: x >= 0

Example:

100

postings. asset · string · required

Example:

"COIN"

postings. destination · string · required

Example:

"users:002"

postings. source · string · required

Example:

"users:001"

script · object

Show child attributes

script. plain · string · required

Example:

"vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n"

script. vars · object

Show child attributes

script.vars. {key} · string

Example:

{ "user": "users:042" }

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

Show child attributes

accountMetadata. {key} · object

Show child attributes

accountMetadata.{key}. {key} · string

Example:

{ "admin": "true" }

force · boolean

Response

200

application/json

OK

data · object · required

Show child attributes

data. timestamp · string<date-time> · required

data. postings · object[] · required

Show child attributes

data.postings. amount · integer<bigint> · required

Required range: x >= 0

Example:

100

data.postings. asset · string · required

Example:

"COIN"

data.postings. destination · string · required

Example:

"users:002"

data.postings. source · string · required

Example:

"users:001"

data. metadata · object · required

Show child attributes

data.metadata. {key} · string

Example:

{ "admin": "true" }

data. id · integer<bigint> · required

Required range: x >= 0

data. reverted · boolean · required

data. insertedAt · string<date-time>

data. updatedAt · string<date-time>

data. reference · string

Example:

"ref:001"

data. revertedAt · string<date-time>

data. preCommitVolumes · object

Show child attributes

data.preCommitVolumes. {key} · object

Show child attributes

data.preCommitVolumes.{key}. {key} · object

Show child attributes

data.preCommitVolumes.{key}.{key}. input · integer<bigint> · required

data.preCommitVolumes.{key}.{key}. output · integer<bigint> · required

data.preCommitVolumes.{key}.{key}. balance · integer<bigint>

Example:

{ "input": 100, "output": 20, "balance": 80 }

Example:

{
  "USD": { "input": 100, "output": 10, "balance": 90 },
  "EUR": { "input": 100, "output": 10, "balance": 90 }
}

Example:

{
  "orders:1": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  },
  "orders:2": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  }
}

data. postCommitVolumes · object

Show child attributes

data.postCommitVolumes. {key} · object

Show child attributes

data.postCommitVolumes.{key}. {key} · object

Show child attributes

data.postCommitVolumes.{key}.{key}. input · integer<bigint> · required

data.postCommitVolumes.{key}.{key}. output · integer<bigint> · required

data.postCommitVolumes.{key}.{key}. balance · integer<bigint>

Example:

{ "input": 100, "output": 20, "balance": 80 }

Example:

{
  "USD": { "input": 100, "output": 10, "balance": 90 },
  "EUR": { "input": 100, "output": 10, "balance": 90 }
}

Example:

{
  "orders:1": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  },
  "orders:2": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  }
}

data. preCommitEffectiveVolumes · object

Show child attributes

data.preCommitEffectiveVolumes. {key} · object

Show child attributes

data.preCommitEffectiveVolumes.{key}. {key} · object

Show child attributes

data.preCommitEffectiveVolumes.{key}.{key}. input · integer<bigint> · required

data.preCommitEffectiveVolumes.{key}.{key}. output · integer<bigint> · required

data.preCommitEffectiveVolumes.{key}.{key}. balance · integer<bigint>

Example:

{ "input": 100, "output": 20, "balance": 80 }

Example:

{
  "USD": { "input": 100, "output": 10, "balance": 90 },
  "EUR": { "input": 100, "output": 10, "balance": 90 }
}

Example:

{
  "orders:1": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  },
  "orders:2": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  }
}

data. postCommitEffectiveVolumes · object

Show child attributes

data.postCommitEffectiveVolumes. {key} · object

Show child attributes

data.postCommitEffectiveVolumes.{key}. {key} · object

Show child attributes

data.postCommitEffectiveVolumes.{key}.{key}. input · integer<bigint> · required

data.postCommitEffectiveVolumes.{key}.{key}. output · integer<bigint> · required

data.postCommitEffectiveVolumes.{key}.{key}. balance · integer<bigint>

Example:

{ "input": 100, "output": 20, "balance": 80 }

Example:

{
  "USD": { "input": 100, "output": 10, "balance": 90 },
  "EUR": { "input": 100, "output": 10, "balance": 90 }
}

Example:

{
  "orders:1": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  },
  "orders:2": {
    "USD": { "input": 100, "output": 10, "balance": 90 }
  }
}