# Send tokens from the Auth Hub wallet

> How a person, an app or an oracle sends any token from the Auth Hub wallet to another address, on the same chain or across chains, after a face check at Self: chains, fees, limits, the API flow, the action card, statuses and error codes.

A send takes a token from a person's Auth Hub wallet and delivers it to someone else's address. It
can stay on the same chain, or cross to another chain through Skip Go, and it can arrive as another
token (for example USDC on ixo arriving as USDC on Base). Every send to someone else's address
starts only after the person passes a face check at Self, bound to exactly that send. Use this page
to understand what a send does, to start one from your own app with the person's key, or to ask
for one from an oracle chat. Moving tokens between the person's own addresses is the same engine
without the face check.

## Where it runs

| Network | Wallet page | API base | Sends |
| --- | --- | --- | --- |
| Mainnet | `https://auth.ixo.earth/wallet/send` | `https://auth.ixo.earth/api/moves` | Available |
| Testnet | | | Not available: moves are off |
| Devnet | | | Not available: moves are off |

Sends run on the Hub's moves engine, and moves are switched off on devnet and testnet. There,
`GET /api/moves/health` answers `{"enabled": false, "status": "disabled"}` and every quote or start
is refused with `503 moves_disabled`. There is no test network for sends: try the smallest amount
on mainnet.

### Chains

On mainnet a send can start on, and arrive on, these chains:

| Chain | Key in the API | Address form |
| --- | --- | --- |
| Base | `base` | `0x` and 40 hex characters |
| Osmosis | `osmosis` | `osmo1…` |
| Noble | `noble` | `noble1…` |
| Cosmos Hub | `cosmoshub` | `cosmos1…` |
| Injective | `injective` | `inj1…` only; a `0x` address is refused |
| ixo | `ixo` | `ixo1…` |

A route may pass through other chains on the way; Skip Go chooses them. Every transaction the
person signs is on one of the Hub's own chains, every address a route uses is the person's own, and
only the last step delivers to the recipient.

USDC arriving on ixo is always `USDC.inj`, the Injective-routed USDC
(`ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6`). Asking for any other USDC
on ixo is mapped to it, and the quote says so with `usdc_on_ixo_pinned: true`.

## What a send is

- **Same chain, same token.** The Hub builds a plain transfer itself: a bank send on a Cosmos chain,
  or a native or ERC-20 transfer on Base. It runs at Standard speed only and takes about a minute.
  An ERC-20 must be a token the Hub knows or one Skip Go lists for that chain; any other contract is
  refused with `send_unverifiable`.
- **Another chain or another token.** Skip Go plans the route (swaps and transfers between chains).
  The Hub signs it with the person's own keys. Every address on the way, and every address funds
  could be returned to, is the person's own. Only the last step delivers to the recipient.
- **Two speeds.** Fast arrives in about a minute when a fast route exists. Standard covers every
  route and can take longer (a quote without Skip Go's estimate shows 20 minutes).
- **One at a time.** A person has at most one move or send running. A second one is refused with
  `409 move_in_progress` until the first ends.
- **The person's own address is not a send.** If the recipient is the person's own address on the
  destination chain, it is a move: no face check, and the quote says `recipient.own: true`. The same
  chain and token to the person's own address is refused with `send_to_self`.

### Every send to another address needs a face check

A send moves money out of the person's reach, so a stolen session, or an app that holds the
person's key, must not be able to make one alone. Before a send to someone else's address starts,
the person passes a [Self Liveness Check](/guides/dev/self-liveness-check) with the credential
comparison: a live video selfie, compared with the photo on the ID behind the person's Self proof of
identity. Self's page shows the amount, the token, the network and the whole recipient address, and
the check is bound to exactly those values. The Hub starts the send only after it verifies Self's
signed result, and one check starts one send.

The person needs a valid Self proof of identity (the `IdentityLevel1` credential) saved in their
Auth Hub wallet. Without one, the check ends with `no_credential`, and the person verifies their ID
first. See [No proof of identity](#no-proof-of-identity).

## Fees and limits

The Hub takes its fee first, in the token being sent, on the chain the send starts from. It is one
transfer from the person's wallet, confirmed on chain before anything else moves. The rest is sent.
What the recipient gets is the quote's `amountOut`; nothing more comes off it.

The fee has a fixed part that depends on the US dollar value the person entered:

| Value entered | Fee |
| --- | --- |
| Up to $10 | $0.10 |
| Over $10 to $500 | $0.50 |
| Over $500 to $1,500 | $1.00 |
| Over $1,500 to $10,000 | $1.50 |
| Over $10,000 | $2.00 |

On top of that, when the wallet is short of a chain's gas coin, the Hub pays the gas and the fee
repays it. The quote's `totalFeeUsd` is the whole cost the person sees: the fixed part, any gas
repayment and the network cost.

| Limit | Value |
| --- | --- |
| Smallest send | $1.00 |
| Largest send | $500,000 |
| Price checks | A route whose price impact or value loss is above 10% is not offered. A quote warns (`high_price_impact`) above 3%. A send stops with `price_moved` when the live loss is more than one point above the quoted loss |
| Running at once | One move or send per person |
| Face checks waiting | 3 per person; a fourth is `429 too_many_open` |
| Face checks at Self | 10 per person per hour; more is `429 check_limit` |
| Face check link | 15 minutes |
| Start after a passed check | Within 1 hour, so a move already running can finish first |
| Quotes | 30 a minute per person |
| Send requests and identity links | 10 a minute per person |
| All `/api/moves` calls | 60 a minute |

The current tiers and limits are also in `GET /api/moves/config` (`fees.tiers`, `limits`).

## Send from the wallet

1. Open the wallet at `https://auth.ixo.earth/wallet` and choose **Send**.
2. Pick the token to send and the chain and token it should arrive as. Enter the amount and the
   recipient's address. The address is checked as you type, and the whole address is shown before
   you go on, with "A send can not be undone."
3. Choose **Review send**. The review shows what leaves, what arrives, the fee, the time and any
   price warning. Choose a speed when both are offered.
4. Choose **Verify it's you**. The page opens Self's face check for this send. Check the amount, the
   network and the whole address on Self's page, then take the short video selfie. It takes about a
   minute.
5. Self sends you back to the wallet. The send starts by itself and the page follows it until it
   arrives. History lists it with the recipient.

If you have no proof of identity yet, the wallet says so before you fill in the form and offers
**Verify my ID**. After the verification the wallet offers **Continue your send** with a fresh quote.

## Send from an app with the person's key

Apps that hold the person's own key call `/api/moves` with a UCAN. The Hub's own pages use the
session cookie instead, and only from the Hub's own origin.

**Authentication.** `Authorization: Bearer <UCAN>`. The UCAN is an invocation issued by the person's
own `did:ixo` (a delegated token is refused), with audience the Hub's DID (`did:web:auth.ixo.earth`),
capability `auth/user/moves` on `ixo:auth-hub:user:<the person's ixo address>`, and an expiry at most
300 seconds ahead. Each invocation is used once: a replay is `409` with `code: replay`. Anything else
is `401 moves_unauthorized`. For UCAN basics, see [Authentication](/guides/dev/authentication).

Amounts are integer base units as strings. Chains are the keys in the [chain table](#chains).

### 1. Get a quote

```http
POST /api/moves/quote
Authorization: Bearer <UCAN>
Content-Type: application/json

{
  "from": { "chain": "ixo", "denom": "ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6" },
  "to": { "chain": "base", "denom": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
  "amount": "5000000",
  "recipient": "0x52908400098527886E0F7030069857D2E4169EE7"
}
```

Send exactly one of `amount` and `all: true` (the whole balance). `recipient` is 1 to 128 characters
with no spaces, exactly as entered. The answer has one quote per speed offered:

```json
{
  "standard": {
    "amountOut": "4380000",
    "minAmountOut": "4336200",
    "usdIn": "5",
    "usdOut": "4.38",
    "feeUsd": "0.1",
    "feeAmount": "100000",
    "feeDenom": "ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6",
    "totalFeeUsd": "0.62",
    "seconds": 1200,
    "priceImpactPercent": "0",
    "valueLossPercent": "0.4",
    "valueLossUsd": "0.02",
    "warnings": []
  },
  "chosen": "standard",
  "recipient": { "address": "0x52908400098527886E0F7030069857D2E4169EE7", "own": false }
}
```

The figures are illustrative. `recipient.address` is the canonical form: EIP-55 on Base, lower-case
bech32 on Cosmos chains.

### 2. Ask for the send

```http
POST /api/moves/send-requests
Authorization: Bearer <UCAN>
Content-Type: application/json
Idempotency-Key: order-7f3c2a91

{
  "from": { "chain": "ixo", "denom": "ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6" },
  "to": { "chain": "base", "denom": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
  "amount": "5000000",
  "recipient": "0x52908400098527886E0F7030069857D2E4169EE7",
  "speed": "standard",
  "quotedLossPercent": "0.4"
}
```

The body is the quote's body plus `speed` (`standard` or `fast`) and, optionally,
`quotedLossPercent` (the quote's `valueLossPercent`). `recipient` is required. The Hub checks the
send exactly as it would start it, fixes its fields for 15 minutes and creates the face check:

```json
{
  "id": "sr_3f9d2c7a1b8e4f6a9c0d1e2f3a4b5c6d",
  "url": "https://self.ixo.earth/c/…",
  "expiresAt": 1795622400,
  "status": "pending",
  "existing": false
}
```

- `201` is a new request. The same send asked again while one is open answers that request: `200`
  with `existing: true` and the same `id`. One send is never checked or sent twice.
- `Idempotency-Key` (optional, 8 to 64 of `A-Z a-z 0-9 _ -`): the same key always answers the same
  request, whatever it became. Another send under the same key is `409 changed`.
- `expiresAt` is in unix seconds.
- Nothing is sent and nothing holds the one-move lock while the person is at the camera.

`POST /api/moves/send-requests/{id}/link` (no body) answers `{ url, expiresAt }` again for a request
that is still `pending`, for example when the person closed Self's page. It is `409 request_closed`
once the request is no longer pending.

### 3. Send the person to the face check

Open `url` in the person's browser, as a top-level page, never in a frame. It works once: the first
device that opens it holds it. The person takes the video selfie on Self's page. A check started
with a UCAN does not return anywhere afterwards; your app follows the request instead.

### 4. Follow the request, then the send

```http
GET /api/moves/send-requests/sr_3f9d2c7a1b8e4f6a9c0d1e2f3a4b5c6d
Authorization: Bearer <UCAN>
```

```json
{
  "id": "sr_3f9d2c7a1b8e4f6a9c0d1e2f3a4b5c6d",
  "status": "started",
  "moveId": "8c1e5b2a-…",
  "reason": null,
  "message": null,
  "expiresAt": 1795622400,
  "startBy": 1795625700
}
```

Poll it every few seconds; the Hub reads Self at most once every 3 seconds per request. When
`status` is `started`, follow the send with `GET /api/moves/moves/{moveId}`. A request that ended
without a send has a `reason` code and a `message` sentence you can show as it is.

| `status` | Meaning |
| --- | --- |
| `pending` | Waiting for the person's face check. `reason: confirming` once the 15 minutes are over and Self's final answer is being read: a pass Self decided in time still counts |
| `verified` | The check passed and the send is being started. `reason: move_in_progress` while another move of the person finishes; it may wait until `startBy` (one hour after the pass) |
| `started` | The send exists: `moveId` |
| `failed` | Nothing was sent. `reason` says why |
| `expired` | Nothing was sent. `reason: expired` (the check was not done in 15 minutes) or `start_timeout` (it passed, but the send could not start within the hour) |

`reason` codes of a `failed` request:

| `reason` | What happened |
| --- | --- |
| `no_credential` | No valid proof of identity at Self for the person. Comes with `url` and `verifyLink` |
| `not_finished` | Self could not finish the check (busy). Nothing about the person. Start again |
| `liveness_failed` | The video selfie did not pass |
| `face_mismatch` | The face did not match the photo on the person's ID |
| `reference_unavailable` | Self could not use the ID's photo |
| `cancelled` | The person said "This wasn't me" |
| `result_invalid` | Self's signed result did not verify. Nothing was sent |
| `verification_unavailable` | Self refused or could not create or read the check |
| `rate_limited`, `check_limit` | A limit at Self when the check was created |
| `card_revoked` | The permission behind an action card ended before its send started |
| A send code such as `sends_disabled`, `route_unavailable` or `price_moved` | The check passed, but the send could not start |
| `error`, or another code | The check could not be finished. Show `message` |

A failed or expired request is never reused. To try again, make a new send request.

### No proof of identity

A check ends `no_credential` when the person has no valid Self proof of identity: none, one that
expired or was revoked, or an approved one that was never saved to their wallet. Self decides it
when the person opens the link, so your app learns it from the request's status, not when it creates
the request.

Get the person a sign-in-free identity link and let them verify their ID:

```http
POST /api/moves/identity-links
Authorization: Bearer <UCAN>
Content-Type: application/json

{ "sendRequestId": "sr_3f9d2c7a1b8e4f6a9c0d1e2f3a4b5c6d" }
```

```json
{ "url": "https://self.ixo.earth/l/…", "expiresAt": "2026-11-20T12:15:00.000Z", "signedIn": true }
```

- The body is optional: `{}` or `{ "sendRequestId": "sr_…" }` (the caller's own request).
- `url` opens Self's identity verification without a sign-in at Self. It is a secret for this
  person only: it works once, lives 15 minutes, and each call makes a new link that replaces the
  earlier unstarted one. Never call this route to poll.
- The proof of identity Self issues is saved to the person's Auth Hub wallet by itself.
- `expiresAt` here is an ISO time.
- Refusals: `409 already_verified` (the person has a proof of identity: make the send request
  again), `409 verification_in_progress` (an earlier identity check is still running), `429
  verify_limit` (Self's limit of 3 identity checks per person in 6 hours; `resetsAt`), `429
  rate_limited`, `503 verification_unavailable` (with `url`, Self's start page with its own sign-in),
  `503 sends_disabled`.

After the person is verified, make a **new** send request. The failed one is never reused.

### What a send looks like

`GET /api/moves/moves/{id}`, `GET /api/moves/moves` (history) and `GET /api/moves/status` return the
same move view as moves do. A send adds `recipient`:

```json
{
  "id": "8c1e5b2a-…",
  "speed": "standard",
  "state": "completed",
  "message": "…",
  "from": { "chain": "ixo", "symbol": "USDC.inj", "amount": "5000000", "…": "…" },
  "to": { "chain": "base", "symbol": "USDC", "amountQuoted": "4380000", "amount": "4391000", "…": "…" },
  "recipient": {
    "address": "0x52908400098527886E0F7030069857D2E4169EE7",
    "chain": "base",
    "delivered": true,
    "returning": false,
    "verified": true,
    "verifiedAt": 1795621610
  }
}
```

| Field | Meaning |
| --- | --- |
| `state` | `moving`, `completed`, `not_sent` (stopped with the funds at the start) or `needs_attention` (IXO's team is checking it) |
| `recipient.delivered` | `true`: the recipient got it. `false`: it ended without reaching them. `null`: not finished |
| `recipient.returning` | Still moving, but back to the person's own wallet on `chain`, never to the recipient |
| `recipient.verified`, `verifiedAt` | The send started from a passed face check, and when Self decided it (unix seconds) |
| `to.amount` | What arrived, once completed |

## When a send cannot be delivered

- **Stopped before anything left the wallet.** The send reads "Not sent" with its reason, for
  example `price_moved` or `insufficient_balance`. Nothing is retried. The person starts again.
- **Failed with the funds still at the start.** The Hub tries the same send again by itself, a few
  times, as long as the face check passed less than 24 hours earlier. Otherwise the person sends
  again.
- **Stopped on the way.** The funds go back to the person's **own** address on the destination
  chain, never to the recipient. The send then reads "Not delivered to …" with `delivered: false`.
  The person sends again by hand.
- **Not known.** If arrival cannot be confirmed, the send reads "Needs attention" and IXO's team
  checks it. A later answer still completes or ends it.
- **The fee.** The fee is taken at the start, so a send that stops after it does not return it. If
  sending was switched off between the fee and the transfer, the move view says `fee.owedBack: true`
  and IXO pays the fee back.

The Hub never treats a balance at the recipient as proof of arrival. A send completes only on a
successful end of its route (or, for a direct transfer, the chain's own result).

## Ask for a send from an oracle chat

An oracle on IXO Channels (for example in WhatsApp) can ask the person to send with the action card
`ixo.wallet.send.v1`. The person reviews and approves it on the Hub, does the face check at Self,
and the Hub runs the send. The card needs `@ixo/action-protocol` 0.10.0 or later: the channel
gateway and the oracle runtime must declare wire level 8. The kind is on for every linked oracle.

```json
{
  "kind": "ixo.wallet.send.v1",
  "network": "ixo mainnet",
  "from": { "chain": "ixo", "denom": "ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6" },
  "to": { "chain": "base", "denom": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
  "recipient": "0x52908400098527886E0F7030069857D2E4169EE7",
  "amountBaseUnits": "5000000",
  "speed": null
}
```

- `network` is the Hub's own network. `amountBaseUnits` is above 0 and never "all". `speed` is
  `standard`, `fast` or `null` (the person picks).
- The card has no title, memo or note from the oracle. Its title
  (`Send <amount> <symbol> to <first 8>…<last 4>`), every sentence and every amount come from the Hub's own checks and a live
  quote. The review page shows the whole address in groups of four and says a send can not be undone.
- The Hub checks the card when it is created, as it checks a send request: `503 sends_disabled`,
  `422 chain_not_allowed`, `400 invalid_recipient`, `422 recipient_not_allowed`, `422 send_to_self`,
  `422 fast_unavailable`, or `400 protocol_version_required` below wire level 8.
- Each approval of a send to someone else makes its own face check (at most 5 per card). A card to
  the person's own address needs none.

Outcomes the oracle receives:

| The send | Outcome |
| --- | --- |
| Arrived (or a move to the person's own address completed) | `succeeded`, receipt `ixo.wallet.sent.v1` with `moveId`, `toChain`, `denom`, `amountBaseUnits` (what arrived), `recipient`, `completedAt` |
| Not sent, not delivered, or the face check ended without a pass | `failed`, receipt `ixo.submission.failed.v1` with `step: "send"` and a `message` to relay |
| Needs attention | `unknown` once; a later end still reports `succeeded` or `failed` |

When a check ends `no_credential`, relay the card's message, let the person verify their ID, then
send a new card. A failed check is never reused.

## How it fits together

```mermaid
sequenceDiagram
  participant App as App or oracle
  participant Hub as Auth Hub
  participant Self as Self
  participant P as Person
  participant Chain as Chains (Skip Go)
  App->>Hub: POST /api/moves/send-requests (or an approved card)
  Hub->>Self: Create a liveness check bound to the send
  Hub-->>App: url of the check
  App->>P: Open the url
  P->>Self: Video selfie, compared with their ID
  Self-->>Hub: Signed result (read by the Hub)
  Hub->>Hub: Verify the signature, the send binding and single use
  Hub->>Chain: Fee first, then the send
  Chain-->>P: The recipient gets the tokens
  App->>Hub: GET /send-requests/{id}, then GET /moves/{moveId}
```

## Error codes

Every refusal is `{ "error": "<code>", "message": "<a sentence to show>" }`.

| Status | `error` | When |
| --- | --- | --- |
| 400 | `invalid_recipient` | Not a valid address for the destination chain |
| 400 | `invalid_amount`, `bad_request` | A malformed amount or body |
| 401 | `moves_unauthorized` | A UCAN that is delegated, not a `did:ixo`, not the person's own, or runs more than 300 seconds |
| 403 | `cross_origin` | A cookie request from another origin |
| 404 | `send_request_not_found` | Not the caller's request |
| 409 | `move_in_progress` | Another move or send is running (`id` names it) |
| 409 | `changed`, `request_closed` | Another send under the same `Idempotency-Key`; a request no longer pending |
| 422 | `verification_required` | `POST /api/moves/moves` with someone else's address: start with a send request |
| 422 | `not_a_send` | A send request to the person's own address: start it as a move |
| 422 | `recipient_not_allowed` | An address that can not receive a send, such as a routing contract |
| 422 | `send_to_self` | The person's own address on the same chain and token |
| 422 | `send_unverifiable` | A same-chain ERC-20 the Hub does not know |
| 422 | `fast_unavailable` | Fast for a same-chain, same-token send |
| 422 | `no_credential` | No valid proof of identity at Self (`url`, `verifyLink`) |
| 422 | `token_not_shown` | The token's name can not be shown exactly on Self's page |
| 422 | `chain_not_allowed`, `route_unavailable`, `insufficient_balance`, `below_minimum`, `above_maximum`, `fee_too_large`, `needs_own_gas`, `tank_short` | The same refusals as a move |
| 429 | `rate_limited` | Too many tries in a short time (`Retry-After`) |
| 429 | `check_limit` | Too many face checks for this person in the last hour (`Retry-After: 3600`) |
| 429 | `too_many_open` | 3 face checks already wait (`open` lists them) |
| 503 | `verification_unavailable` | Self can not be reached. Nothing was sent |
| 503 | `sends_disabled`, `moves_disabled` | Sending is off on this network |

## Known limits

- **The route is Skip Go's.** The Hub checks that the route is the one it asked for, signed only by
  the person's own addresses and spending only the token requested on a Cosmos chain. It trusts
  Skip Go to deliver the last step to the recipient.
- **A face check proves the person at the camera.** It shows that a live person matches the identity
  Self holds for the account. It does not show that this identity is the account owner's. See
  [What a pass proves](/guides/dev/self-liveness-check#what-a-pass-proves).
- **Two different sends are two checks.** A send whose amount, recipient, token, chain or speed
  differs is another send with its own face check, even while the first is still waiting.
- **Contract addresses.** A 32-byte Cosmos contract address is accepted as a recipient. A contract
  that can not hold funds is the sender's risk.

## Related pages

<CardGroup cols={2}>
  <Card title="Self Liveness Check" icon="camera" href="/guides/dev/self-liveness-check">
    The face check behind every send, and how a third party uses it.
  </Card>
  <Card title="Hold and share credentials" icon="wallet" href="/guides/dev/credentials/hold-and-share">
    The Auth Hub wallet and the Self proof of identity a send needs.
  </Card>
  <Card title="Authentication" icon="key" href="/guides/dev/authentication">
    UCAN invocations and which interface needs which.
  </Card>
  <Card title="What works today" icon="table" href="/status">
    Where each capability is available.
  </Card>
</CardGroup>
