Author a contract from scratch

Create a template with one participant and one text parameter. The complete example records an acknowledgement; its machine-readable instruction performs no payment or token creation. The XML passes the documented local schema checks. Template approval and signing still need verification on your development service. Arrange that service access before running the submission steps.

Prerequisites

Complete your first Agent API call.
Have an approved Legal Identity and its signing key metadata and password.
Confirm your provider accepts the urn:nf:iot:leg:sc:1.0 contract schema and the payment instruction namespace used below.
Use the sandbox automatic approval process or arrange operator review. Submitting a template does not mean it is already approved.
Use an XML editor or validator that supports XSD validation; follow local XML validation.

1. Define the contract

Download acknowledgement.xml. The complete file is shown below; you can also start with an empty file and add its sections in this order.

Section	Purpose	What you can adapt
`contract` attributes	Set visibility, template eligibility, duration, and archival periods	Review these periods and visibility with your provider and participants.
`Nop`	Supply a schema-defined machine-readable instruction	Replace it only with a supported instruction and its exact schema.
`role`	Require one `Participant`	Keep this name aligned with the API’s `Parts` entry.
`parts`	Mark the document as a template	The instance receives actual Legal Identity identifiers.
`parameters`	Require `Subject`, between 1 and 120 characters	Keep the API parameter name and human text reference aligned.
`humanReadableText`	Explain the acknowledgement and retention terms	Present the resulting instance text before requesting a signature.

<?xml version="1.0" encoding="utf-8"?>
<contract xmlns="urn:nf:iot:leg:sc:1.0"
          canActAsTemplate="true" visibility="CreatorAndParts"
          duration="P1M" archiveReq="P1M" archiveOpt="P1M">
  <Nop xmlns="https://paiwise.tagroot.io/Schema/PaymentInstructions.xsd" />
  <role name="Participant" minCount="1" maxCount="1">
    <description xml:lang="en"><paragraph><text>The participant acknowledging the stated subject.</text></paragraph></description>
  </role>
  <parts><templateOnly /></parts>
  <parameters>
    <stringParameter name="Subject" minLength="1" maxLength="120">
      <description xml:lang="en"><paragraph><text>The subject the participant will review.</text></paragraph></description>
    </stringParameter>
  </parameters>
  <humanReadableText xml:lang="en">
    <paragraph><text>The participant acknowledges reviewing: </text><parameter name="Subject" /><text>.</text></paragraph>
    <paragraph><text>This demonstration records an acknowledgement. It instructs no payment and creates no token. The instance lasts one month, followed by one month of required archival and one month of optional archival.</text></paragraph>
  </humanReadableText>
</contract>

2. Validate the file

Load the contract schema set in your XML validator and validate the complete acknowledgement.xml file using these steps. Expected result: the schema set compiles and the contract has no XML validation errors. Correct invalid namespaces, missing required fields, or element ordering before submission. If you introduce a custom machine-readable element, also create its XSD, load it in the local namespace map, and confirm the provider’s schema resolution requirements. An arbitrary XML payload is not a verified provider-supported instruction.

3. Propose the template

Send the following requests over HTTPS with your account’s exact host, JWT, and application URL as Referer. Replace every placeholder before sending a request. Base64-encode the complete file’s UTF-8 bytes, then send:

POST /Agent/Legal/ProposeTemplate HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "templateBase64": "<BASE64_OF_COMPLETE_UTF8_XML>"
}

The templateBase64 field contains that encoded XML. Propose Template returns Template. Record its identifier. In the sandbox, the submitted template enters automatic review. On other Neurons, give the identifier to the operator to arrange approval. See Contract approval. Retrieve it with Legal/GetContract using the request shown below and the template identifier to observe its lifecycle. Continue only when its state is Approved. If it remains Proposed or is Rejected, contact the operator before creating an instance.

4. Create an instance

Send the approved template identifier and the participant’s approved Legal Identity to Legal/CreateContract:

POST /Agent/Legal/CreateContract HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "templateId": "<APPROVED_TEMPLATE_ID>",
  "visibility": "CreatorAndParts",
  "Parts": [{ "role": "Participant", "legalId": "<APPROVED_LEGAL_ID>" }],
  "Parameters": [{ "name": "Subject", "value": "A demonstration subject for review" }]
}

Record the returned Contract identifier separately from the template identifier. The role and parameter names are case-sensitive names from the template. Do not send empty arrays for this example.

5. Review and sign the instance

Retrieve the created instance using its identifier:

POST /Agent/Legal/GetContract HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "contractId": "<CONTRACT_ID>"
}

Present its human-readable text, parameters, participant identity, and Participant role to the signer. If any value is wrong, stop before signing. Use the participant’s existing key and its password. Calculate keySignature and requestSignature from the contract signature formulas, using the key’s keyId, localName, and namespace, the account password, and a fresh nonce. Bind the signature to the reviewed contractId, legalId, and role Participant. The key namespace is algorithm metadata retained during key creation. It is not the contract XML namespace. After the signer confirms the exact contract and role, submit the signature explicitly:

POST /Agent/Legal/SignContract HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "keyId": "<SIGNER_KEY_ID>",
  "legalId": "<SIGNER_LEGAL_ID>",
  "contractId": "<REVIEWED_CONTRACT_ID>",
  "role": "Participant",
  "nonce": "<FRESH_NONCE>",
  "keySignature": "<CALCULATED_KEY_SIGNATURE>",
  "requestSignature": "<CALCULATED_REQUEST_SIGNATURE>"
}

Retrieve the instance again with Legal/GetContract and the same contractId. Check the returned participant signature and contract lifecycle state. A successful signature request alone does not establish that every provider requirement is satisfied. For multiple parties, repeat review and signing in each party’s authorized application session using the contract lifecycle guide.

Recover and retain the result

Failure	Next action
Template still proposed or rejected	Retrieve its status and resolve the provider review. Do not repeatedly create instances.
Missing participant or invalid subject	Correct the `Parts` or `Parameters` values against the approved template.
Signature rejected	Check approved identity, assigned role, exact host, key metadata, and the two distinct passwords. Generate a fresh nonce.
Request times out after submission	Retrieve the known object or reconcile with the provider before retrying a write. These operations do not document an idempotency guarantee.

Retain the template ID, instance ID, reviewed parameters, participant identity, and observed signature/lifecycle result. The example defines duration and archival periods; deleting your local files does not delete a signed contract. Follow the provider’s supported lifecycle and retention rules. Continue with a token and state machine, or adapt a LegalLab example to a different agreement.

Build an application

Verified identity

Sign-in and signatures

Contracts and agreements

Tokens and digital assets

Wallets and payments

Other application tasks

Prerequisites

1. Define the contract

2. Validate the file

3. Propose the template

4. Create an instance

5. Review and sign the instance

Recover and retain the result

​Prerequisites

​1. Define the contract

​2. Validate the file

​3. Propose the template

​4. Create an instance

​5. Review and sign the instance

​Recover and retain the result

Prerequisites

1. Define the contract

2. Validate the file

3. Propose the template

4. Create an instance

5. Review and sign the instance

Recover and retain the result