> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-reference-full-stack-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /registry/allocation-instruction/v2/allocation-factory

> Get the factory and choice context for creating allocations using the `AllocationFactory_Allocate` choice. Registries MAY limit the size of the allocations that they support. To ensure wide compatibility with apps, registries MUST support creating allocations that involve at most 25 transfer legs.

<div class="x2mdx-ref-page x2mdx-ref-page--operation x2mdx-ref-page--manual-api" />

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">Get the factory and choice context for creating allocations using the `AllocationFactory_Allocate` choice. Registries MAY limit the size of the allocations that they support. To ensure wide compatibility with apps, registries MUST support creating allocations that involve at most 25 transfer legs.</p>

  <div class="x2mdx-ref-badges">
    <span class="x2mdx-ref-badge x2mdx-ref-badge--protocol">OpenAPI</span>

    <a class="x2mdx-ref-badge x2mdx-ref-badge--added" href="#history-added-0-6-11">Added 0.6.11</a>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url 'https://example.com/registry/allocation-instruction/v2/allocation-factory' \
    --header 'Content-Type: application/json' \
    --data '{
    "choiceArguments": {},
    "excludeDebugFields": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import json
  import requests

  url = "https://example.com/registry/allocation-instruction/v2/allocation-factory"
  headers = {'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "choiceArguments": {},
    "excludeDebugFields": false
  }''')
  response = requests.request(
      "POST", url, headers=headers, json=payload
  )

  print(response.text)
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://example.com/registry/allocation-instruction/v2/allocation-factory', {
    method: 'POST',
    headers: {
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "choiceArguments": {},
    "excludeDebugFields": false
  }),
  });

  console.log(await response.text());
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://example.com/registry/allocation-instruction/v2/allocation-factory',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "choiceArguments": {},
    "excludeDebugFields": false
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Content-Type: application/json"
      ],
  ]);

  $response = curl_exec($curl);
  echo $response;
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  package main

  import (
    "bytes"
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    req, _ := http.NewRequest("POST", "https://example.com/registry/allocation-instruction/v2/allocation-factory", bytes.NewBufferString(`{
    "choiceArguments": {},
    "excludeDebugFields": false
  }`))
    req.Header.Set("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(req)
    defer response.Body.Close()
    body, _ := io.ReadAll(response.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  var request = HttpRequest.newBuilder()
      .uri(URI.create("https://example.com/registry/allocation-instruction/v2/allocation-factory"))
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "choiceArguments": {},
    "excludeDebugFields": false
  }
  """))
      .build();
  var response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={"theme":{"light":"github-light","dark":"github-dark"}}
  require 'net/http'
  require 'uri'

  uri = URI('https://example.com/registry/allocation-instruction/v2/allocation-factory')
  request = Net::HTTP::Post.new(uri)
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "choiceArguments": {},
    "excludeDebugFields": false
  }
  JSON
  response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(request)
  end
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "factoryId": "<string>",
    "choiceContext": {
      "choiceContextData": {},
      "disclosedContracts": [
        {
          "templateId": "<string>",
          "contractId": "<string>",
          "createdEventBlob": "<string>",
          "synchronizerId": "<string>",
          "debugPackageName": "<string>",
          "debugPayload": {},
          "debugCreatedAt": "2026-01-01T00:00:00Z"
        }
      ]
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": "<string>"
  }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": "<string>"
  }
  ```

  ```json 409 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": "<string>"
  }
  ```
</ResponseExample>

## Body

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ParamField body="choiceArguments" type="object" required>
  The arguments that are intended to be passed to the choice provided by the factory. To avoid repeating the Daml type definitions, they are specified as JSON objects. However the concrete format is given by how the choice arguments are encoded using the Daml JSON API (with the `extraArgs.context` and `extraArgs.meta` fields set to the empty object). The choice arguments are provided so that the registry can also provide choice-argument specific contracts, e.g., the configuration for a specific instrument-id.
</ParamField>

<ParamField body="excludeDebugFields" type="boolean" default="false">
  If set to true, the response will not include fields prefixed with 'debug'. Useful to save bandwidth.
</ParamField>

## Responses

### 200

ok

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="factoryId" type="string" required>
  The contract ID of the contract implementing the factory interface.
</ResponseField>

<ResponseField name="choiceContext" type="ChoiceContext" required>
  The context required to exercise a choice on a contract via an interface. Used to retrieve additional reference data that is passed in via disclosed contracts, which are in turn referred to via their contract ID in the `choiceContextData`. Asset implementations SHOULD avoid that this value depends on contract-ids passed in the choice arguments, so that clients can prefetch choice contexts when chaining multiple token standard actions together in a single Daml transaction.

  <Expandable title="child attributes">
    <ResponseField name="choiceContextData" type="object" required>
      The additional data to use when exercising the choice.
    </ResponseField>

    <ResponseField name="disclosedContracts" type="DisclosedContract[]" required>
      The contracts that are required to be disclosed to the participant node for exercising the choice.

      <Expandable title="child attributes">
        <ResponseField name="templateId" type="string" required>
          The fully qualified template identifier of the disclosed contract.
        </ResponseField>

        <ResponseField name="contractId" type="string" required>
          The contract ID of the disclosed contract.
        </ResponseField>

        <ResponseField name="createdEventBlob" type="string" required>
          The serialized created event of the disclosed contract, forwarded unchanged as retrieved from the JSON Ledger API.
        </ResponseField>

        <ResponseField name="synchronizerId" type="string" required>
          The synchronizer to which the contract is currently assigned. If the contract is in the process of being reassigned, then a "409" response is returned.
        </ResponseField>

        <ResponseField name="debugPackageName" type="string">
          The name of the Daml package that was used to create the contract. Use this data only if you trust the provider, as it might not match the data in the `createdEventBlob`.
        </ResponseField>

        <ResponseField name="debugPayload" type="object">
          The contract arguments that were used to create the contract. Use this data only if you trust the provider, as it might not match the data in the `createdEventBlob`.
        </ResponseField>

        <ResponseField name="debugCreatedAt" type="string (date-time)">
          The ledger effective time at which the contract was created. Use this data only if you trust the provider, as it might not match the data in the `createdEventBlob`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 400

bad request

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

### 404

not found

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

### 409

conflict

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

## History

<div class="x2mdx-ref-history" aria-label="Reference history">
  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--introduced" id="history-added-0-6-11">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Added</span>
      <code class="x2mdx-ref-history-event-version">0.6.11</code>
    </div>
  </div>
</div>