> ## 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 /v0/wallet/transfer-offers

> Create an offer to directly transfer a given amount of Amulet to another party. Direct transfers are a three-step process: 1. The sender creates a transfer offer 2. The receiver accepts the offer 3. The sender's wallet automation consumes the accepted offer and transfers the amount. Amulets are not locked for direct transfers. If the sender's wallet does not have enough Amulet to fulfill the offer at this point, the transfer will fail.

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

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">Create an offer to directly transfer a given amount of Amulet to another party. Direct transfers are a three-step process: 1. The sender creates a transfer offer 2. The receiver accepts the offer 3. The sender's wallet automation consumes the accepted offer and transfers the amount. Amulets are not locked for direct transfers. If the sender's wallet does not have enough Amulet to fulfill the offer at this point, the transfer will fail.</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-5-10">Added 0.5.10</a>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://example.com/api/validator/v0/wallet/transfer-offers' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests

  url = "https://example.com/api/validator/v0/wallet/transfer-offers"
  headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }''')
  response = requests.request(
      "POST", url, headers=headers, json=payload
  )

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://example.com/api/validator/v0/wallet/transfer-offers', {
    method: 'POST',
    headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }),
  });

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

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://example.com/api/validator/v0/wallet/transfer-offers',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer <token>",
          "Content-Type: application/json"
      ],
  ]);

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

  ```go Go theme={null}
  package main

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

  func main() {
    req, _ := http.NewRequest("POST", "https://example.com/api/validator/v0/wallet/transfer-offers", bytes.NewBufferString(`{
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }`))
    req.Header.Set("Authorization", "Bearer <token>")
    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={null}
  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/api/validator/v0/wallet/transfer-offers"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }
  """))
      .build();
  var response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  uri = URI('https://example.com/api/validator/v0/wallet/transfer-offers')
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer <token>'
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "receiver_party_id": "<string>",
    "amount": "<string>",
    "description": "<string>",
    "expires_at": 123,
    "tracking_id": "<string>"
  }
  JSON
  response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(request)
  end
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "offer_contract_id": "<string>"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 429 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 500 theme={null}
  {
    "error": "<string>"
  }
  ```
</ResponseExample>

## Authorizations

### walletUserAuth

<ParamField header="Authorization" type="string" required>
  HTTP bearer authentication. Send the token as `Authorization: Bearer &lt;token&gt;`. Bearer format: `JWT`. JWT token as described by the `spliceAppBearerAuth` security scheme. The subject of the token must be ledger API user of the user whose wallet the endpoint affects.
</ParamField>

## Body

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

<ParamField body="receiver_party_id" type="string" required>
  The party id of the receiver.
</ParamField>

<ParamField body="amount" type="string" required>
  The amount of Amulet to transfer.
</ParamField>

<ParamField body="description" type="string" required>
  An arbitrary, user chosen text. This should be a human readable string that describes the purpose of the transfer. It will be shown to the receiver when they decide whether to accept the offer.
</ParamField>

<ParamField body="expires_at" type="number" required>
  OpenAPI type: <code>integer (int64)</code>.

  Expiry time of the transfer offer as unix timestamp in microseconds. After this time, the offer can no longer be accepted and automation in the wallet will eventually expire the transfer offer. Note that this time is compared against the ledger effective time of the Daml transaction accepting or expiring an offer, and can skew from the wall clock time measured on the caller's machine. See [https://docs.daml.com/concepts/time.html](https://docs.daml.com/concepts/time.html) for how ledger effective time is bound to the record time of a transaction on a domain.
</ParamField>

<ParamField body="tracking_id" type="string" required>
  Tracking id to support exactly once submission. Once submitted, all successive calls with the same tracking id will get rejected with a 409 or 429 status code unless the command fails and the offer did not get created. Clients should create a fresh tracking id when they try to create a new transfer offer. If that command submission fails with a retryable error or the application crashed and got restarted, successive command submissions must reuse the same tracking id to ensure they don't create the same offer multiple times.
</ParamField>

## Responses

### 200

The transfer offer has been created.

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

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

### 400

Invalid request, check the error response for details.

<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

The submitter’s wallet could not be 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

A transfer offer with the same tracking id has been created. Check the status endpoint for the current status.

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

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

### 429

A transfer offer with the same tracking id is currently being processed, which may or may not succeed. Retry submitting the request with exponential back-off.

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

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

### 500

internal server error

<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-5-10">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Added</span>
      <code class="x2mdx-ref-history-event-version">0.5.10</code>
    </div>
  </div>
</div>