# Create On-Chain Transfer

Creates an on-chain USDC transfer (withdrawal) from a Jiko pocket to an external crypto wallet counterparty.
The counterparty must be a `LINKED` crypto wallet counterparty owned by the pocket's customer.
- A counterparty that does not exist, or belongs to another customer, returns `412` `CounterpartyNotFoundError`.
- A counterparty that is not `LINKED` (`PENDING`, `FAILED`, `UNLINKED` or `EXTERNAL_ACCOUNT_CLOSED`) returns `412` `CounterpartyNotVerifiedError`.
- A pocket that does not exist returns `422` `JikoAccountNotFoundError`.
- A pocket that is not `OPEN`, or is not a `JIKO_PAY` pocket, returns `412` `PocketNotEligibleError`.
- An amount over the maximum for a single transfer returns `412` `TransferMaxLimitError`.
- An amount that would take the customer over their daily withdrawal limit returns `412` `TransferDailyLimitError`.
- An amount that is not greater than the withdrawal minimum returns `412` `TransferMinimumAmountError`.
- A `transfer_id` that was already used with a different request body returns `409` `IntegrityError`.

None of these create a transfer.
Creating on-chain transfers isn't available by default and must be enabled; contact your Jiko point of contact to learn more. Requests made without it enabled are rejected with a `403`.
The transfer is returned in a `PROCESSING` state and moves to `COMPLETED` or `FAILED`. Status updates are delivered via [Webhooks](/products/partner-api/guides/building/webhooks) as `transfers.crypto.withdrawal.success` and `transfers.crypto.withdrawal.rejected` events.

Endpoint: POST /api/v1/transfers/on-chain/
Version: Version: 25c7baee
Security: HTTPBearer

## Security:

  - `HTTPBearer` (unknown)
    http bearer

## Header parameters:

  - `x-jiko-idempotency` (string, required)
    A new UUID that you generate for each request, reads included. It is part of the request signature and prevents replay of a request. A value that was already sent in the last hour is rejected with `409 jiko.errors.DuplicateRequestError`, even if the first request failed. When you retry a request, generate a new value and sign the request again.

  - `x-jiko-signature` (string, required)
    Base64-encoded HMAC-SHA256 hash of `x-jiko-idempotency + request pathname + body`, keyed with your shared secret. See [Authentication](/products/partner-api/guides/building/auth) for the full algorithm and a code sample.

## Request fields (application/json):

  - `transfer_id` (any)
    Optional client-generated transfer ID for idempotency

  - `pocket_id` (string, required)
    Also known as jiko_account_id

  - `counterparty_id` (string, required)
    ID of the verified crypto wallet counterparty

  - `amount_usdc` (integer, required)
    USD cents, e.g. $10.50 is `1050`.

  - `description` (any)
    Optional note for the sender's own tracking. It is stored with the transfer and is not sent on-chain to the receiver.

## Response 201:

  - `201` (unknown)
    Successful Response

## Response 201 fields (application/json):

  - `id` (string, required)

  - `status` (string, required)
    Enum: "PROCESSING", "COMPLETED", "REJECTED", "FAILED"

  - `pocket_id` (string, required)

  - `counterparty_id` (any, required)

  - `amount` (object, required)

  - `amount.value` (integer, required)
    USD values are always in cents.

  - `amount.currency` (string, required)

  - `amount.formatted` (string)

  - `time_created` (string, required)

  - `description` (any)

  - `transaction_hash` (any)

  - `direction` (string, required)
    Enum: "INCOMING", "OUTGOING"

  - `counterparty_wallet_address` (any)

  - `object_type` (string, required)

## Response 401:

  - `401` (unknown)
    The access token is missing, invalid or expired.

## Response 401 fields (application/json):

  - `type` (string, required)

  - `instance` (string, required)

  - `detail` (string, required)

  - `trace_id` (any)

  - `fields` (any)
    Present only on input validation errors. Each entry identifies one invalid field: `loc` is its location, `msg` is the problem, and `type` is the validation rule that failed.

## Response 403:

  - `403` (unknown)
    `x-jiko-signature` does not match the request, or the access token does not permit this action.

## Response 403 fields (application/json):

  - `type` (string, required)

  - `instance` (string, required)

  - `detail` (string, required)

  - `trace_id` (any)

  - `fields` (any)
    Present only on input validation errors. Each entry identifies one invalid field: `loc` is its location, `msg` is the problem, and `type` is the validation rule that failed.

## Response 422:

  - `422` (unknown)
    Validation Error

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

  - `detail.input` (any)

  - `detail.ctx` (object)

