Sign in
ledger.v1

Execute a Numscript

This route is deprecated, and has been merged into POST /{ledger}/transactions.

post/{ledger}/script

Path parameters

ledgerstring required
Example:ledger001

Name of the ledger.

Query parameters

previewboolean
Example:true

Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request body

plainstring required

The Numscript program to execute

varsobject

Values bound to the script's declared variables, keyed by variable name

referencestring

Reference to attach to the generated transaction

metadataMetadata nullable

Arbitrary key/value pairs attached to the resource

Example request

{
  "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
  "vars": {
    "user": "users:042"
  },
  "reference": "order_1234"
}

Response

On success, it will return a 200 status code, and the resulting transaction under the transaction field.

On failure, it will also return a 200 status code, and the following fields:

  • details: contains a URL. When there is an error parsing Numscript, the result can be difficult to read—the provided URL will render the error in an easy-to-read format.
  • errorCode and error_code (deprecated): contains the string code of the error
  • errorMessage and error_message (deprecated): contains a human-readable indication of what went wrong, for example that an account had insufficient funds, or that there was an error in the provided Numscript.
errorCode'INTERNAL' | 'INSUFFICIENT_FUND' | 'VALIDATION' | 'CONFLICT' | 'NO_SCRIPT' | 'COMPILATION_FAILED' | 'METADATA_OVERRIDE' | 'NOT_FOUND' | 'TIMEOUT'

Machine-readable error code identifying the failure

errorMessagestring

Human-readable description of the error

detailsstring

Optional link carrying additional context about the error, such as a Numscript playground URL reproducing it

Example response

{
  "errorCode": "INSUFFICIENT_FUND",
  "errorMessage": "account had insufficient funds",
  "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9",
  "transaction": {
    "postings": [
      {
        "amount": 100,
        "asset": "COIN",
        "destination": "users:002",
        "source": "users:001"
      }
    ],
    "reference": "ref:001",
    "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
        }
      }
    }
  }
}

Changes