> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walley.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# The HTTP API

> Call Walley's REST API directly: authentication, ledger reads, and transaction submission over plain HTTPS.

Everything the SDKs do goes through this API. If you're not working in Python or TypeScript, you can call it yourself.

<Info>
  Most integrations should use the [Python SDK](/python-sdk/overview) or [TypeScript dApp SDK](/build/overview). They handle tokens, signing, and retries for you. Call the HTTP API directly when you're working in a language without a Walley SDK.
</Info>

## Authentication

Reads need a bearer token, which you get through the auth endpoints by proving you hold the party's Ed25519 key:

```bash theme={null}
# 1. Ask for a challenge
curl -X POST https://api.walley.cc/v1/auth/challenge
# { "challenge": "...", "expires_at": ... }

# 2. Sign the challenge string's exact bytes with your Ed25519 key.
#    Sign it as-is. Do not base64-decode it first.

# 3. Trade the signature for a token
curl -X POST https://api.walley.cc/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{ "party_id": "...", "public_key": "<base64 DER SPKI>",
        "challenge": "...", "signature": "<base64>" }'
# { "access_token": "...", "expires_at": ... }
```

Tokens are short-lived, we recommend having logic such that when a request comes back `401`, you mint a new token and retry.

## Reading the ledger

`/v1/proxy/` forwards to the participant's [Canton JSON Ledger API](https://docs.digitalasset.com/), so any Ledger API documentation or client works here. Swap in the base URL and attach your token:

```bash theme={null}
OFFSET=$(curl -s https://api.walley.cc/v1/proxy/v2/state/ledger-end \
  -H "Authorization: Bearer $TOKEN" | jq .offset)

curl -s https://api.walley.cc/v1/proxy/v2/state/active-contracts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"filter\":{\"filtersByParty\":{\"$PARTY\":{}}},\"verbose\":false,\"activeAtOffset\":$OFFSET}"
```

The token can only read your own party's contracts. By default an unfiltered query returns every active contract your party has.

## Submitting transactions

The same prepare, sign, submit loop the SDKs run:

```bash theme={null}
# 1. Prepare: send your Daml commands, get back the transaction to sign
curl -X POST https://api.walley.cc/v1/transactions/prepare \
  -H "Content-Type: application/json" \
  -d '{ "commands": { ... }, "fee_payer": "<your party id>" }'
# {
#   "transaction": { "prepared_transaction": "...", "prepared_transaction_hash": "...", ... },
#   "fee_amount": "0.03",
#   "token": "..."
# }

# 2. Sign the prepared_transaction_hash with your Ed25519 key

# 3. Submit, passing the token from prepare
curl -X POST https://api.walley.cc/v1/transactions/submit-and-wait \
  -H "Content-Type: application/json" \
  -d '{ "party_id": "...", "transaction": { "...": "signed" }, "token": "..." }'
```

The fee is quoted at prepare (`fee_amount`, in CC) and drawn from the same prepaid traffic balance as every other Walley path. If you have traffic balance, that's it: the fee comes out of the balance and there is nothing extra to sign or pay per transaction. If the balance can't cover the fee, Walley fronts that one transaction and the balance goes negative; further prepares are refused with HTTP 402 until you top the balance back up.

`submit` returns as soon as the submission is accepted; `submit-and-wait` blocks until the transaction commits.

<Warning>
  Submissions are authorized by your signature, not the bearer token. The API cannot author or sign commands on your behalf.
</Warning>

## Limits

* Reads run as your party only.
* Request bodies on the ledger proxy are capped at 10 MB, and per-IP rate limits apply.

## Connecting

| Network | Base URL |
| - | - |
| MainNet | `https://api.walley.cc` |
| DevNet | `https://api.dev.walley.cc` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.